@zudojs/permissions 1.0.0 → 1.2.0

package/README.md

@@ -2,6 +2,12 @@
 
 Generic authorization engine with RBAC, ABAC, resource authorization, wildcards, role hierarchy, policies, and abilities.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-permissions](https://zudojs.oyinlola.site/docs/packages-permissions) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-permissions.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -102,8 +108,19 @@ 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.
+Conditions may be async. 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** whose condition throws **applies**. In the example above,
+  `locked-posts` throws when no resource is passed, and the check is denied —
+  treating the deny as unmet would let the role's allow win. The error is
+  reported through `onError`, and the decision is not cached.
+
+A deny also bears on a wildcard check: `can(actor, "post:*")` is refused by a
+deny on `post:delete`, whether it comes from `deniedPermissions`, a deny rule,
+or a policy registered for `post:delete`.
 
 **Combining.** The default is `deny-overrides`: any applicable deny wins,
 whatever its priority. Pass `algorithm: "priority"` for highest-priority-wins,
@@ -118,13 +135,19 @@ Conditions read request-scoped facts from `context.metadata`, supplied per
 check:
 
 ```typescript
+import { requireCurrentTenant } from "@zudojs/tenancy";
+
 await engine.can(actor, "invoice:read", invoice, {
-  metadata: { tenantId: request.tenantId },
+  // The *verified* tenant — resolved and trust-checked by @zudojs/tenancy.
+  metadata: { tenantId: requireCurrentTenant().id },
 });
 ```
 
 `tenantIsolation()` compares that value against the resource's tenant, and
-denies when either is missing.
+denies when either is missing. It is only as good as the value you pass: fill
+`tenantId` from a source the client cannot choose (a verified token claim, or
+the tenant `@zudojs/tenancy` resolved), **never from a request header** — a
+caller would set the header to the resource's tenant and pass.
 
 ## Policies
 
@@ -151,8 +174,8 @@ const engine = createPermissionEngine({
 
 Policies run highest priority first and stop at the first denial. A policy
 that throws, or exceeds `policyTimeout`, denies. A denying policy always wins;
-an allowing one can grant access the rules did not, but never overrides a
-denial.
+an allowing one can grant access the rules did not decide, but never overrides
+a denial — from another policy or from a deny rule that applied.
 
 `policyTimeout: 0` means "expire immediately", not "no timeout" — omit it to
 disable.
@@ -176,7 +199,11 @@ const policies = createPolicyRegistry();
 const engine = createPermissionEngine({ roles, policies });
 
 roles.define({ name: "auditor", permissions: ["audit:read"] });
-engine.invalidateRoles(); // pick up the change
+roles.remove("reader");
+// both take effect on the next check: the engine subscribes to the registry
+
+policies.define({ name: "lockdown", permissions: ["*:*"], evaluate: () => ({ allowed: false }) });
+// enforced by the next check — through the engine or an existing Ability
 
 roles.require("auditor"); // throws RoleNotFoundError when unregistered
 ```
@@ -185,9 +212,17 @@ 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.
+The engine subscribes to a role or policy registry it is given. Every
+`define`, `remove` and `clear` discards the memoized roles **and every cached
+decision**, so revoking a role is not undone by a cache entry written before
+the revocation. `engine.invalidateRoles()` does the same for a custom source.
+
+`validateConfiguration` (default `true`) rejects a pattern that could never
+match wherever it is written — a role grant, a role's rules, a static rule, or
+a policy's `permissions` — because a malformed pattern in a deny or a lockdown
+policy would fail open in silence. Arrays are checked at construction; a
+registry checks on `define` (`InvalidRoleError` / `InvalidPermissionError`),
+and a custom source is checked when the engine reads it.
 
 A permission registry records descriptions and implications:
 
@@ -223,9 +258,13 @@ 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.
+Keys include the actor id, a digest of everything else the actor carries
+(`roles`, `permissions`, `type`, any other field a condition may read), the
+permission and the resource id (from `resource.id`, or `options.resourceId`).
+The same user id with different roles — an admin token in one tenant and a
+viewer token in another, or a demoted token — never shares a decision. A `|`
+inside an actor or resource id is escaped, so two different checks can never
+share a key either.
 
 A check is cached only when the key can describe it completely:
 
@@ -235,7 +274,10 @@ A check is cached only when the key can describe it completely:
 - 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;
+- an actor carrying something the digest cannot describe (a function, a class
+  instance, a `Map`) is **not cached**;
+- a decision produced by a policy marked `cacheable: false`, or forced by a
+  condition that threw, is not stored;
 - a TTL of `0` or less means "do not cache".
 
 `deniedPermissions` is evaluated before the cache is consulted, so a deny
@@ -264,7 +306,10 @@ Every failure denies:
 | --------------------------- | ------------------------------------------------------ |
 | Unknown role on the actor   | denied; reported to `onError`; other roles still apply |
 | Malformed permission string | denied, `reason: "invalid_permission"`                 |
-| Condition throws            | rule does not apply                                    |
+| Allow condition throws      | the allow does not apply                               |
+| Deny condition throws       | denied, `reason: "rule_deny"`; reported to `onError`   |
+| Malformed rule/policy pattern | rejected at construction or `define`                 |
+| A deny rule applies         | denied, `reason: "rule_deny"`, even if a policy allows |
 | Policy throws or times out  | denied, `reason: "policy_error:<name>"`                |
 | Role inheritance cycle      | denied; reported to `onError`                          |
 | Role source throws          | denied; reported to `onError`                          |
@@ -319,8 +364,10 @@ 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.
+Every check emits — allowed, denied, and the ones that throw — including
+`explain()` on the engine and on an Ability, which make the same real
+decision. A handler that throws cannot break authorization, but it is reported
+rather than swallowed.
 
 ## HTTP middleware
 
@@ -329,10 +376,13 @@ 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")),
+  // May be async: it is awaited, and a loader that rejects denies (403).
+  extractResource: (context) => loadPost(context.request.getParam?.("id")),
+  // The tenant @zudojs/tenancy resolved and trust-checked — never a header.
   extractMetadata: (context) => ({
-    tenantId: context.request.headers.get("x-tenant"),
+    tenantId: context.state.get<{ tenantId: string }>("tenancy:context")?.tenantId,
   }),
+  onError: (error, source) => logger.warn({ error, source }, "guard denied"),
 });
 ```
 
@@ -346,11 +396,16 @@ const guard = authorize(engine, "post:update", {
   decision.
 - `context.signal` is forwarded, so a client disconnect stops policy
   evaluation.
+- `extractResource` is awaited. A loader that throws or rejects answers
+  **403** (`reason: "resource_error"`) and reports through `onError`; it never
+  lets the request through.
 - `createRequirePermissionsMiddleware(engine, permissions, { mode })` checks
   several permissions, short-circuiting on the first that decides the outcome.
+  An empty list denies in either mode.
 
-`@zudojs/http` is an optional peer dependency; the middleware types are
-mirrored locally so this package works without it.
+The middleware composes with the real `@zudojs/http` pipeline without
+depending on it: the HTTP types are mirrored structurally (headers, params and
+query may be plain objects, as `@zudojs/http` provides them, or maps).
 
 ## Errors
 

package/dist/ability/ability.core.js

@@ -5,33 +5,13 @@
  */
 import { evaluate, evaluateWithTrace } from "../evaluator/evaluator.core.js";
 import { PermissionDeniedError } from "../permissionErrors/index.js";
+import { observed } from "../evaluator/engineSupport/index.js";
 /**
  * Create an Ability for an actor.
  */
 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,
-            });
-        }
+    function run(permission, resource, options) {
+        return observed(emitter, actor, permission, resource, () => evaluate(actor, permission, resource, evaluatorOptions, options), (decision) => decision);
     }
     return {
         actor,
@@ -45,7 +25,7 @@ export function createAbility(actor, evaluatorOptions, emitter) {
             return run(permission, resource, options);
         },
         async explain(permission, resource, options) {
-            return evaluateWithTrace(actor, permission, resource, evaluatorOptions, options);
+            return observed(emitter, actor, permission, resource, () => evaluateWithTrace(actor, permission, resource, evaluatorOptions, options), (result) => result.decision);
         },
         async authorize(permission, resource, options) {
             const decision = await run(permission, resource, options);

package/dist/cache/cache.actorDigest.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Actor digest for the decision cache key.
+ *
+ * A decision depends on everything the actor carries, not only its id:
+ * `roles`, `permissions` and `type` travel on the actor object for each
+ * request (a tenant-scoped token, `auth.checkAccess`), and a condition may
+ * read any other field on it. Keying on the id alone let an admin decision
+ * made in one tenant answer for the same user as a viewer in another, and a
+ * demoted token keep its old grants until the entry expired.
+ *
+ * @module cache/cache.actorDigest
+ */
+import type { PermissionActor } from "../permissionTypes/index.js";
+/** Longest digest worth keying on; a longer one is not cached at all. */
+export declare const MAX_ACTOR_DIGEST_LENGTH = 4096;
+/**
+ * A stable description of everything an actor carries besides its id.
+ *
+ * Returns `undefined` when the actor holds something the digest cannot
+ * describe faithfully — a function, a class instance, a `Map`, nesting past
+ * six levels, or a digest longer than {@link MAX_ACTOR_DIGEST_LENGTH}. The
+ * engine does not cache such a decision rather than key it on a partial
+ * description.
+ */
+export declare function actorCacheDigest(actor: PermissionActor): string | undefined;
+//# sourceMappingURL=cache.actorDigest.d.ts.map

package/dist/cache/cache.actorDigest.js

@@ -0,0 +1,90 @@
+/**
+ * Actor digest for the decision cache key.
+ *
+ * A decision depends on everything the actor carries, not only its id:
+ * `roles`, `permissions` and `type` travel on the actor object for each
+ * request (a tenant-scoped token, `auth.checkAccess`), and a condition may
+ * read any other field on it. Keying on the id alone let an admin decision
+ * made in one tenant answer for the same user as a viewer in another, and a
+ * demoted token keep its old grants until the entry expired.
+ *
+ * @module cache/cache.actorDigest
+ */
+/** Longest digest worth keying on; a longer one is not cached at all. */
+export const MAX_ACTOR_DIGEST_LENGTH = 4096;
+/** Deepest nesting the digest will describe. */
+const MAX_DEPTH = 6;
+/** Marks a value the digest cannot describe faithfully. */
+const UNDESCRIBABLE = Symbol("undescribable");
+function isPlainRecord(value) {
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function canonical(value, depth) {
+    if (depth > MAX_DEPTH)
+        return UNDESCRIBABLE;
+    if (value === null)
+        return "null";
+    switch (typeof value) {
+        case "string":
+        case "boolean":
+            return JSON.stringify(value);
+        case "number":
+            return Number.isFinite(value) ? JSON.stringify(value) : UNDESCRIBABLE;
+        case "object":
+            break;
+        default:
+            return UNDESCRIBABLE;
+    }
+    const object = value;
+    if (object instanceof Date) {
+        const time = object.getTime();
+        return Number.isNaN(time) ? UNDESCRIBABLE : `D${JSON.stringify(time)}`;
+    }
+    if (Array.isArray(object)) {
+        const parts = [];
+        for (const entry of object) {
+            const part = canonical(entry, depth + 1);
+            if (part === UNDESCRIBABLE)
+                return UNDESCRIBABLE;
+            parts.push(part);
+        }
+        return `[${parts.join(",")}]`;
+    }
+    if (!isPlainRecord(object))
+        return UNDESCRIBABLE;
+    return canonicalRecord(object, depth, []);
+}
+function canonicalRecord(record, depth, skip) {
+    const parts = [];
+    for (const key of Object.keys(record).sort()) {
+        if (skip.includes(key))
+            continue;
+        const entry = record[key];
+        if (entry === undefined)
+            continue;
+        const part = canonical(entry, depth + 1);
+        if (part === UNDESCRIBABLE)
+            return UNDESCRIBABLE;
+        parts.push(`${JSON.stringify(key)}:${part}`);
+    }
+    return `{${parts.join(",")}}`;
+}
+/**
+ * A stable description of everything an actor carries besides its id.
+ *
+ * Returns `undefined` when the actor holds something the digest cannot
+ * describe faithfully — a function, a class instance, a `Map`, nesting past
+ * six levels, or a digest longer than {@link MAX_ACTOR_DIGEST_LENGTH}. The
+ * engine does not cache such a decision rather than key it on a partial
+ * description.
+ */
+export function actorCacheDigest(actor) {
+    if (typeof actor !== "object" || actor === null)
+        return undefined;
+    const digest = canonicalRecord(actor, 0, ["id"]);
+    if (digest === UNDESCRIBABLE)
+        return undefined;
+    return digest.length > MAX_ACTOR_DIGEST_LENGTH ? undefined : digest;
+}
+//# sourceMappingURL=cache.actorDigest.js.map

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

@@ -8,9 +8,16 @@ import type { PermissionCache } from "../permissionTypes/index.js";
  * Generate a cache key for a permission check.
  *
  * The actor id is delimited, so invalidating actor `1` cannot also clear
- * actors `10` and `123`.
+ * actors `10` and `123`, and a delimiter inside an id is escaped so two
+ * different (actor, permission, resource) triples can never share a key.
+ *
+ * `scope` carries whatever else the decision depends on — the engine passes
+ * a digest of the actor's roles, permissions and attributes, so the same id
+ * holding different grants never shares a key. It sits after the actor
+ * prefix behind a `~`, which no permission string can start with, so
+ * `invalidateActor` still finds every entry for the actor.
  */
-export declare function permissionCacheKey(actorId: string, permission: string, resourceId?: string): string;
+export declare function permissionCacheKey(actorId: string, permission: string, resourceId?: string, scope?: string): string;
 /** Options for {@link createMemoryPermissionCache}. */
 export interface MemoryPermissionCacheOptions {
     /** Default TTL in milliseconds. Defaults to 60,000 (1 minute). */

package/dist/cache/cache.core.js

@@ -5,19 +5,41 @@
  */
 /** Separates the actor id from the rest of the key. */
 const KEY_DELIMITER = "|";
+/**
+ * Escape a caller-supplied segment so it cannot forge a delimiter.
+ *
+ * Actor and resource ids are opaque strings and may contain `|`. Without
+ * escaping, actor `u|post:read` checking `x:y` produced the same key as
+ * actor `u` checking `post:read` on resource `x:y` — one actor's cached
+ * decision answering for another. Ids without `|` or `\` are unchanged, so
+ * existing keys keep their shape.
+ */
+function escapeSegment(segment) {
+    return segment.replace(/[\\|]/g, (char) => `\\${char}`);
+}
 /** Prefix identifying an actor's cache entries. */
 function actorPrefix(actorId) {
-    return `actor:${actorId}${KEY_DELIMITER}`;
+    return `actor:${escapeSegment(actorId)}${KEY_DELIMITER}`;
 }
 /**
  * Generate a cache key for a permission check.
  *
  * The actor id is delimited, so invalidating actor `1` cannot also clear
- * actors `10` and `123`.
+ * actors `10` and `123`, and a delimiter inside an id is escaped so two
+ * different (actor, permission, resource) triples can never share a key.
+ *
+ * `scope` carries whatever else the decision depends on — the engine passes
+ * a digest of the actor's roles, permissions and attributes, so the same id
+ * holding different grants never shares a key. It sits after the actor
+ * prefix behind a `~`, which no permission string can start with, so
+ * `invalidateActor` still finds every entry for the actor.
  */
-export function permissionCacheKey(actorId, permission, resourceId) {
-    const base = `${actorPrefix(actorId)}${permission}`;
-    return resourceId ? `${base}${KEY_DELIMITER}${resourceId}` : base;
+export function permissionCacheKey(actorId, permission, resourceId, scope) {
+    const scoped = scope === undefined ? "" : `~${escapeSegment(scope)}${KEY_DELIMITER}`;
+    const base = `${actorPrefix(actorId)}${scoped}${permission}`;
+    return resourceId
+        ? `${base}${KEY_DELIMITER}${escapeSegment(resourceId)}`
+        : base;
 }
 const DEFAULT_TTL_MS = 60_000;
 const DEFAULT_MAX_ENTRIES = 10_000;

package/dist/cache/index.d.ts

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

package/dist/cache/index.js

@@ -4,4 +4,5 @@
  * @module cache
  */
 export { createMemoryPermissionCache, permissionCacheKey, } from "./cache.core.js";
+export { actorCacheDigest, MAX_ACTOR_DIGEST_LENGTH, } from "./cache.actorDigest.js";
 //# sourceMappingURL=index.js.map

package/dist/evaluator/authorizationEngine.d.ts

@@ -6,14 +6,27 @@
 import type { PermissionActor, PermissionDecision, ExplainResult, PermissionRule, PermissionPolicyDefinition, PermissionCache, PermissionResolver, RoleResolver, RoleDefinition, RuleCombiningAlgorithm, AuthorizationOptions } from "../permissionTypes/index.js";
 import { type Ability } from "../ability/ability.core.js";
 import type { PermissionEventEmitter } from "../observability/observability.core.js";
-/** Anything the engine will accept as its source of roles. */
+/**
+ * Anything the engine will accept as its source of roles.
+ *
+ * A source with `subscribe` (every `createRoleRegistry()`) is watched: a
+ * `define`, `remove` or `clear` discards the engine's memoized roles and
+ * every cached decision, so revoking a role takes effect on the next check.
+ */
 export interface RoleSource {
     get(name: string): RoleDefinition | undefined;
+    subscribe?(listener: () => void): () => void;
 }
-/** Anything the engine will accept as its source of policies. */
+/**
+ * Anything the engine will accept as its source of policies.
+ *
+ * A source with `subscribe` (every `createPolicyRegistry()`) is watched the
+ * same way, so a policy added or removed is not bypassed by a cached decision.
+ */
 export interface PolicySource {
     names(): readonly string[];
     get(name: string): PermissionPolicyDefinition | undefined;
+    subscribe?(listener: () => void): () => void;
 }
 /** Configuration for the permission engine. */
 export interface PermissionEngineOptions {
@@ -79,7 +92,11 @@ export interface PermissionEngine {
     createAbility(actor: PermissionActor): Ability;
     /** Drop cached decisions for one actor. */
     invalidateActor(actorId: string): Promise<void>;
-    /** Re-read the role source, discarding the memoized lookups. */
+    /**
+     * Re-read the role source, discarding the memoized lookups and every
+     * cached decision. Registries created with `createRoleRegistry()` and
+     * `createPolicyRegistry()` trigger this themselves on every change.
+     */
     invalidateRoles(): void;
 }
 /**