@zudojs/permissions 0.1.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zudojs Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -11,27 +11,358 @@ npm install @zudojs/permissions
 ## Quick Start
 
 ```typescript
-import { createPermissionEngine } from "@zudojs/permissions";
+import {
+  createPermissionEngine,
+  createPermissionActor,
+} from "@zudojs/permissions";
 
 const engine = createPermissionEngine({
-  roles: {
-    admin: { permissions: ["user:*", "post:*"] },
-    editor: { permissions: ["post:read", "post:write"] },
-  },
+  roles: [
+    { name: "reader", permissions: ["post:read"] },
+    { name: "editor", permissions: ["post:update"], inherits: ["reader"] },
+    { name: "admin", permissions: ["*:*"] },
+  ],
 });
 
-const allowed = await engine.check("admin", "user", "delete");
+const actor = createPermissionActor("user_1", { roles: ["editor"] });
+
+await engine.can(actor, "post:update"); // true
+await engine.can(actor, "post:read"); // true — inherited from "reader"
+await engine.can(actor, "user:delete"); // false
+```
+
+`roles` is an array of `RoleDefinition`, and every check takes the **actor**,
+not a role name. Malformed configuration is rejected at construction: a grant
+like `"post"` (no action) could never match, so it is an error rather than a
+silent no-op.
+
+## Permissions
+
+Permissions are `resource:action`. Two wildcard forms are supported, and they
+mean the same thing everywhere — in a grant, a deny, a rule, or a policy:
+
+| Pattern          | Matches                                   |
+| ---------------- | ----------------------------------------- |
+| `post:read`      | exactly that                              |
+| `post:*`         | every action on `post`                    |
+| `*:read`         | `read` on every resource                  |
+| `*:*`            | everything                                |
+| `billing.*:read` | `billing:read`, `billing.invoice:read`, … |
+
+A partial wildcard such as `post*:read` is rejected: the matcher has no
+meaning for it, so accepting one would register a grant that never matches.
+
+## Denies
+
+`deniedPermissions` is matched with the same rules as grants, so a wildcard
+deny works:
+
+```typescript
+const restricted = createPermissionActor("user_2", {
+  roles: ["admin"],
+  deniedPermissions: ["*:delete", "billing.*:read"],
+});
+
+await engine.can(restricted, "post:delete"); // false
+await engine.can(restricted, "post:read"); // true
+```
+
+An explicit deny short-circuits before any rule or policy runs.
+
+## Rules and ABAC
+
+A `PermissionRule` carries an optional **condition**, and the rule applies
+only when that condition holds. This is what makes "owners may edit their own
+posts" expressible:
+
+```typescript
+import { isOwner, tenantIsolation, allOf } from "@zudojs/permissions";
+
+const engine = createPermissionEngine({
+  roles,
+  rules: [
+    {
+      name: "own-posts",
+      effect: "allow",
+      resource: "post",
+      action: "update",
+      condition: isOwner(), // compares resource.ownerId to actor.id
+    },
+    {
+      name: "locked-posts",
+      effect: "deny",
+      resource: "post",
+      action: "update",
+      condition: (context) => Boolean((context.resource as Post).locked),
+    },
+  ],
+});
+
+await engine.can(actor, "post:update", { ownerId: "user_1" }); // true
+await engine.can(actor, "post:update", { ownerId: "user_9" }); // false
+```
+
+Conditions may be async. A condition that throws is treated as unmet — an
+authorization check fails closed.
+
+**Combining.** The default is `deny-overrides`: any applicable deny wins,
+whatever its priority. Pass `algorithm: "priority"` for highest-priority-wins,
+where a tie still goes to deny.
+
+Combinators: `allOf`, `anyOf`, `not`, `always`, `never`, `isOwner`,
+`tenantIsolation`, `metadataEquals`, `resourceEquals`.
+
+### Request metadata
+
+Conditions read request-scoped facts from `context.metadata`, supplied per
+check:
+
+```typescript
+await engine.can(actor, "invoice:read", invoice, {
+  metadata: { tenantId: request.tenantId },
+});
+```
+
+`tenantIsolation()` compares that value against the resource's tenant, and
+denies when either is missing.
+
+## Policies
+
+A policy is a named, prioritised hook that runs alongside the rules.
+
+```typescript
+const engine = createPermissionEngine({
+  roles,
+  policyTimeout: 250,
+  policies: [
+    {
+      name: "business-hours",
+      permissions: ["post:*"], // wildcards work here too
+      priority: 10, // higher runs first
+      cacheable: false, // depends on the clock, so never cache it
+      evaluate: (context) =>
+        isBusinessHours()
+          ? { allowed: true }
+          : { allowed: false, reason: "outside_business_hours" },
+    },
+  ],
+});
+```
+
+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.
+
+`policyTimeout: 0` means "expire immediately", not "no timeout" — omit it to
+disable.
+
+## Registries
+
+Registries can be handed straight to the engine, and stay live:
+
+```typescript
+import {
+  createRoleRegistry,
+  createPolicyRegistry,
+  createPermissionRegistry,
+} from "@zudojs/permissions";
+
+const roles = createRoleRegistry();
+roles.define({ name: "reader", permissions: ["post:read"] });
+roles.define({ name: "staff", permissions: [], inherits: ["reader"] });
+
+const policies = createPolicyRegistry();
+const engine = createPermissionEngine({ roles, policies });
+
+roles.define({ name: "auditor", permissions: ["audit:read"] });
+engine.invalidateRoles(); // pick up the change
+
+roles.require("auditor"); // throws RoleNotFoundError when unregistered
+```
+
+All three registries reject a duplicate name — re-registering a role or a
+policy is an authorization rule disappearing without a trace. Pass
+`{ allowOverride: true }` when replacement is what you mean.
+
+`validateConfiguration` (default `true`) applies to a registry as well as to
+an inline array: a role whose grant could never match is rejected when the
+engine looks it up, and the check denies.
+
+A permission registry records descriptions and implications:
+
+```typescript
+const permissions = createPermissionRegistry();
+permissions.define("post:admin", { implies: ["post:write"] });
+permissions.define("post:write", { implies: ["post:read"] });
+
+const engine = createPermissionEngine({
+  roles,
+  expandImplied: (permission) => permissions.expandImplied(permission),
+});
+// An actor granted post:admin now passes post:read.
+```
+
+## Caching
+
+```typescript
+import { createMemoryPermissionCache } from "@zudojs/permissions";
+
+const engine = createPermissionEngine({
+  roles,
+  cache: createMemoryPermissionCache({
+    defaultTtlMs: 30_000,
+    maxEntries: 5_000,
+  }),
+  cacheTtlMs: 30_000,
+});
+
+await engine.can(actor, "post:read", post); // evaluated
+await engine.can(actor, "post:read", post); // cached
+await engine.can(actor, "post:read", post, { skipCache: true });
+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.
+
+A check is cached only when the key can describe it completely:
+
+- a resource with no `id` and no `options.resourceId` is **not cached**, since
+  the key would collapse to actor + permission and an allow for one object
+  would answer for the next;
+- a check carrying `metadata` is **not cached**, because conditions such as
+  `tenantIsolation()` read the tenant from there and it is not part of the
+  key;
+- a decision produced by a policy marked `cacheable: false` is not stored;
+- a TTL of `0` or less means "do not cache".
+
+`deniedPermissions` is evaluated before the cache is consulted, so a deny
+added to the actor takes effect immediately rather than waiting for a cached
+allow to expire. A malformed entry there can never match, so it is reported
+through `onError` instead of being dropped in silence.
+
+## External sources
+
+```typescript
+const engine = createPermissionEngine({
+  roles,
+  roleResolver: { resolveRoles: (actor) => db.rolesFor(actor.id) },
+  permissionResolver: { resolvePermissions: (actor) => db.rulesFor(actor.id) },
+});
+```
+
+A resolver that fails is reported through `onError` and the check continues
+fail-closed, rather than throwing out of the authorization path.
+
+## 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"`                 |
+| Condition throws            | rule does not apply                                    |
+| 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
+the original as `cause`.
+
+Cancellation is the one case that throws, because the caller asked for the
+work to stop.
+
+## Abilities
+
+```typescript
+const ability = engine.createAbility(actor);
+
+await ability.can("post:update", post);
+await ability.cannot("post:delete");
+await ability.check("post:update", post); // full decision
+await ability.authorize("post:update", post); // throws PermissionDeniedError
+await ability.explain("post:update", post);
+```
+
+## Explain
+
+`explain` runs the same evaluation as `check` and collects the steps, so the
+trace always describes the decision that was made:
+
+```typescript
+const { allowed, steps, decision } = await engine.explain(
+  actor,
+  "post:update",
+  post,
+);
+steps.forEach((step) => console.log(step.type, step.detail, step.matched));
+```
+
+The trace lists the grants that bear on this decision, not every permission
+the actor holds.
+
+## Audit events
+
+```typescript
+import { createPermissionEventEmitter } from "@zudojs/permissions";
+
+const emitter = createPermissionEventEmitter({
+  onHandlerError: (error) => logger.error({ error }, "audit sink failed"),
+});
+emitter.on((event) => auditLog.write(event));
+
+const engine = createPermissionEngine({ roles, emitter });
+```
+
+Every check emits — allowed, denied, and the ones that throw. A handler that
+throws cannot break authorization, but it is reported rather than swallowed.
+
+## HTTP middleware
+
+```typescript
+import { authorize, createActorMiddleware } from "@zudojs/permissions";
+
+const guard = authorize(engine, "post:update", {
+  extractActor: (context) => context.state.get("auth:user"),
+  extractResource: (context) => loadPost(context.request.params.get("id")),
+  extractMetadata: (context) => ({
+    tenantId: context.request.headers.get("x-tenant"),
+  }),
+});
 ```
 
-## Features
+- The guard extracts the actor itself when one is not already in state, so it
+  works without a separate actor middleware.
+- No actor → **401** with `WWW-Authenticate`. Actor but not permitted →
+  **403**.
+- The 403 body carries `decision.publicReason`, never the internal reason:
+  `policy_error:<name>` names your policies and does not belong in a
+  response. Pass `deniedResponse` to shape the body — it receives the real
+  decision.
+- `context.signal` is forwarded, so a client disconnect stops policy
+  evaluation.
+- `createRequirePermissionsMiddleware(engine, permissions, { mode })` checks
+  several permissions, short-circuiting on the first that decides the outcome.
+
+`@zudojs/http` is an optional peer dependency; the middleware types are
+mirrored locally so this package works without it.
+
+## Errors
+
+`PermissionError` is the base. `PermissionDeniedError` carries a caller-safe
+message; the actor id, reason and policy live on `error.details` for the log,
+not in the exposed metadata.
 
-- Role-Based Access Control (RBAC)
-- Attribute-Based Access Control (ABAC)
-- Resource authorization with wildcards
-- Role hierarchy and inheritance
-- Policy engine
-- Ability-based checks
-- Explain mode for debugging
+`PermissionNotFoundError` · `DuplicatePermissionError` · `RoleNotFoundError` ·
+`DuplicateRoleError` · `DuplicatePolicyError` · `InvalidPermissionError` ·
+`InvalidRoleError` ·
+`CircularRoleInheritanceError` · `PolicyError` · `PolicyTimeoutError` ·
+`PermissionResolverError` · `AuthorizationAbortedError`
 
 ## Use Cases
 

package/dist/ability/ability.core.d.ts

@@ -5,6 +5,7 @@
  */
 import type { PermissionActor, PermissionDecision, ExplainResult, AuthorizationOptions } from "../permissionTypes/index.js";
 import type { EvaluatorOptions } from "../evaluator/evaluator.pipeline.js";
+import type { PermissionEventEmitter } from "../observability/observability.core.js";
 /**
  * An Ability provides fast permission checks for a pre-resolved actor.
  */
@@ -25,5 +26,5 @@ export interface Ability {
 /**
  * Create an Ability for an actor.
  */
-export declare function createAbility(actor: PermissionActor, evaluatorOptions: EvaluatorOptions): Ability;
+export declare function createAbility(actor: PermissionActor, evaluatorOptions: EvaluatorOptions, emitter?: PermissionEventEmitter): Ability;
 //# sourceMappingURL=ability.core.d.ts.map

package/dist/ability/ability.core.js

@@ -3,33 +3,58 @@
  *
  * @module ability/ability
  */
-import { evaluate, evaluateWithExplain } from "../evaluator/evaluator.core.js";
+import { evaluate, evaluateWithTrace } from "../evaluator/evaluator.core.js";
 import { PermissionDeniedError } from "../permissionErrors/index.js";
 /**
  * Create an Ability for an actor.
  */
-export function createAbility(actor, evaluatorOptions) {
+export function createAbility(actor, evaluatorOptions, emitter) {
+    async function run(permission, resource, options) {
+        const start = performance.now();
+        let decision;
+        let failure;
+        try {
+            decision = await evaluate(actor, permission, resource, evaluatorOptions, options);
+            return decision;
+        }
+        catch (error) {
+            failure = error;
+            throw error;
+        }
+        finally {
+            emitter?.emit({
+                actorId: actor.id,
+                permission,
+                allowed: decision?.allowed ?? false,
+                reason: decision?.reason ??
+                    (failure instanceof Error ? `error:${failure.name}` : undefined),
+                durationMs: performance.now() - start,
+                errored: failure !== undefined,
+            });
+        }
+    }
     return {
         actor,
         async can(permission, resource, options) {
-            const decision = await evaluate(actor, permission, resource, evaluatorOptions, options);
-            return decision.allowed;
+            return (await run(permission, resource, options)).allowed;
         },
         async cannot(permission, resource, options) {
-            return !(await this.can(permission, resource, options));
+            return !(await run(permission, resource, options)).allowed;
         },
         async check(permission, resource, options) {
-            return evaluate(actor, permission, resource, evaluatorOptions, options);
+            return run(permission, resource, options);
         },
         async explain(permission, resource, options) {
-            return evaluateWithExplain(actor, permission, resource, evaluatorOptions, options);
+            return evaluateWithTrace(actor, permission, resource, evaluatorOptions, options);
         },
         async authorize(permission, resource, options) {
-            const decision = await evaluate(actor, permission, resource, evaluatorOptions, options);
+            const decision = await run(permission, resource, options);
             if (!decision.allowed) {
-                throw new PermissionDeniedError(decision.reason ?? "Access denied", {
+                throw new PermissionDeniedError(decision.publicReason ?? "Access denied", {
                     actorId: actor.id,
                     permission,
+                    reason: decision.reason,
+                    policy: decision.policy,
                 });
             }
         },

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

@@ -5,13 +5,32 @@
  */
 import type { PermissionCache } from "../permissionTypes/index.js";
 /**
- * Create an in-memory permission cache.
+ * Generate a cache key for a permission check.
  *
- * @param defaultTtlMs - Default TTL in milliseconds. Defaults to 60000 (1 minute).
+ * The actor id is delimited, so invalidating actor `1` cannot also clear
+ * actors `10` and `123`.
  */
-export declare function createMemoryPermissionCache(defaultTtlMs?: number): PermissionCache;
+export declare function permissionCacheKey(actorId: string, permission: string, resourceId?: string): string;
+/** Options for {@link createMemoryPermissionCache}. */
+export interface MemoryPermissionCacheOptions {
+    /** Default TTL in milliseconds. Defaults to 60,000 (1 minute). */
+    readonly defaultTtlMs?: number;
+    /**
+     * Maximum entries held. The oldest are evicted past it. Default: 10,000.
+     *
+     * Keys carry actor and resource ids, so an unbounded cache grows with
+     * traffic — and this one holds authorization decisions, which is the last
+     * place to want unbounded retention.
+     */
+    readonly maxEntries?: number;
+}
 /**
- * Generate a cache key for a permission check.
+ * Create an in-memory permission cache.
+ *
+ * A TTL of `0` or less means "do not cache", not "cache forever" — the
+ * inverse is a decision that outlives the grant that produced it.
  */
-export declare function permissionCacheKey(actorId: string, permission: string, resourceId?: string): string;
+export declare function createMemoryPermissionCache(optionsOrTtl?: MemoryPermissionCacheOptions | number): PermissionCache & {
+    size(): number;
+};
 //# sourceMappingURL=cache.core.d.ts.map

package/dist/cache/cache.core.js

@@ -3,49 +3,91 @@
  *
  * @module cache/cache
  */
+/** Separates the actor id from the rest of the key. */
+const KEY_DELIMITER = "|";
+/** Prefix identifying an actor's cache entries. */
+function actorPrefix(actorId) {
+    return `actor:${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`.
+ */
+export function permissionCacheKey(actorId, permission, resourceId) {
+    const base = `${actorPrefix(actorId)}${permission}`;
+    return resourceId ? `${base}${KEY_DELIMITER}${resourceId}` : base;
+}
+const DEFAULT_TTL_MS = 60_000;
+const DEFAULT_MAX_ENTRIES = 10_000;
 /**
  * Create an in-memory permission cache.
  *
- * @param defaultTtlMs - Default TTL in milliseconds. Defaults to 60000 (1 minute).
+ * A TTL of `0` or less means "do not cache", not "cache forever" — the
+ * inverse is a decision that outlives the grant that produced it.
  */
-export function createMemoryPermissionCache(defaultTtlMs = 60000) {
+export function createMemoryPermissionCache(optionsOrTtl = {}) {
+    const options = typeof optionsOrTtl === "number"
+        ? { defaultTtlMs: optionsOrTtl }
+        : optionsOrTtl;
+    const defaultTtlMs = options.defaultTtlMs ?? DEFAULT_TTL_MS;
+    const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
     const store = new Map();
+    function evictIfNeeded() {
+        if (store.size <= maxEntries)
+            return;
+        const now = Date.now();
+        for (const [key, entry] of store) {
+            if (entry.expiresAt !== undefined && now > entry.expiresAt) {
+                store.delete(key);
+            }
+        }
+        // Map iterates in insertion order, so the head is the oldest entry.
+        while (store.size > maxEntries) {
+            const oldest = store.keys().next();
+            if (oldest.done === true)
+                break;
+            store.delete(oldest.value);
+        }
+    }
     return {
         async get(key) {
             const entry = store.get(key);
             if (!entry)
                 return undefined;
-            if (entry.expiresAt && Date.now() > entry.expiresAt) {
+            if (entry.expiresAt !== undefined && Date.now() > entry.expiresAt) {
                 store.delete(key);
                 return undefined;
             }
             return entry.value;
         },
-        async set(key, value, options) {
-            const ttl = options?.ttl ?? defaultTtlMs;
-            store.set(key, {
-                value,
-                expiresAt: ttl > 0 ? Date.now() + ttl : undefined,
-            });
+        async set(key, value, setOptions) {
+            const ttl = setOptions?.ttl ?? defaultTtlMs;
+            if (ttl <= 0) {
+                store.delete(key);
+                return;
+            }
+            store.delete(key);
+            store.set(key, { value, expiresAt: Date.now() + ttl });
+            evictIfNeeded();
         },
         async delete(key) {
             store.delete(key);
         },
         async invalidateActor(actorId) {
-            const prefix = `actor:${actorId}`;
-            for (const key of store.keys()) {
-                if (key.startsWith(prefix)) {
+            const prefix = actorPrefix(actorId);
+            for (const key of [...store.keys()]) {
+                if (key.startsWith(prefix))
                     store.delete(key);
-                }
             }
         },
+        async clear() {
+            store.clear();
+        },
+        size() {
+            return store.size;
+        },
     };
 }
-/**
- * Generate a cache key for a permission check.
- */
-export function permissionCacheKey(actorId, permission, resourceId) {
-    const base = `actor:${actorId}:${permission}`;
-    return resourceId ? `${base}:${resourceId}` : base;
-}
 //# sourceMappingURL=cache.core.js.map

package/dist/cache/index.d.ts

@@ -3,5 +3,5 @@
  *
  * @module cache
  */
-export { createMemoryPermissionCache, permissionCacheKey, } from "./cache.core.js";
+export { createMemoryPermissionCache, permissionCacheKey, type MemoryPermissionCacheOptions, } from "./cache.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/conditions/conditions.core.d.ts

@@ -1,6 +1,9 @@
 /**
  * Condition combinators for composing authorization policies.
  *
+ * Conditions are evaluated by the rule engine: attach one to a
+ * `PermissionRule` and the rule applies only when it returns `true`.
+ *
  * @module conditions/conditions
  */
 import type { PermissionConditionFn } from "../permissionTypes/index.js";
@@ -33,8 +36,21 @@ export declare function isOwner(ownerField?: string): PermissionConditionFn;
 /**
  * Enforce tenant isolation — actor and resource must share the same tenant.
  *
- * @param actorTenantField - Field on actor metadata holding tenant ID. Defaults to "tenantId".
- * @param resourceTenantField - Field on resource holding tenant ID. Defaults to "tenantId".
+ * The actor's tenant is read from `context.metadata`, which is supplied per
+ * check through `AuthorizationOptions.metadata`:
+ *
+ * ```ts
+ * engine.check(actor, "invoice:read", invoice, {
+ *   metadata: { tenantId: request.tenantId },
+ * });
+ * ```
+ *
+ * @param actorTenantField - Key in the context metadata holding the actor's tenant. Defaults to "tenantId".
+ * @param resourceTenantField - Field on the resource holding the tenant ID. Defaults to "tenantId".
  */
 export declare function tenantIsolation(actorTenantField?: string, resourceTenantField?: string): PermissionConditionFn;
+/** Check that a value in the context metadata equals an expected value. */
+export declare function metadataEquals(key: string, expected: unknown): PermissionConditionFn;
+/** Check that the resource field matches the expected value. */
+export declare function resourceEquals(field: string, expected: unknown): PermissionConditionFn;
 //# sourceMappingURL=conditions.core.d.ts.map