@zudojs/permissions 1.2.0 → 1.4.0

package/README.md

@@ -135,11 +135,15 @@ Conditions read request-scoped facts from `context.metadata`, supplied per
 check:
 
 ```typescript
-import { requireCurrentTenant } from "@zudojs/tenancy";
+import { createContextManager, getDefaultStorage } from "@zudojs/tenancy";
+
+const tenancy = createContextManager({ storage: getDefaultStorage() });
 
 await engine.can(actor, "invoice:read", invoice, {
   // The *verified* tenant — resolved and trust-checked by @zudojs/tenancy.
-  metadata: { tenantId: requireCurrentTenant().id },
+  // `requireCurrentTenant()` is a method on the context manager; it throws
+  // when no tenant context is active, rather than returning undefined.
+  metadata: { tenantId: tenancy.requireCurrentTenant().id },
 });
 ```
 
@@ -149,33 +153,95 @@ denies when either is missing. It is only as good as the value you pass: fill
 the tenant `@zudojs/tenancy` resolved), **never from a request header** — a
 caller would set the header to the resource's tenant and pass.
 
+Enforce it as a **deny** rule, `not(tenantIsolation())`:
+
+```typescript
+import { createPermissionEngine, not, tenantIsolation } from "@zudojs/permissions";
+
+const engine = createPermissionEngine({
+  roles: [{ name: "accountant", permissions: ["invoice:read"] }],
+  rules: [
+    {
+      name: "tenant-isolation",
+      effect: "deny",
+      resource: "invoice",
+      action: "*",
+      condition: not(tenantIsolation()), // other tenant, or no tenant → deny
+    },
+  ],
+});
+```
+
+A conditional **allow** rule with `tenantIsolation()` only adds a way in: a
+role that grants `invoice:read` allows the check whatever the condition says,
+so that role reads every tenant's invoices. The deny form refuses cross-tenant
+access even for roles that hold the permission, and no policy can override it.
+
 ## Policies
 
-A policy is a named, prioritised hook that runs alongside the rules.
+A policy is a named, prioritised hook that runs alongside the rules. By
+default it is an **extra condition on top of RBAC/ABAC**: it can take access
+away, never hand it out.
 
 ```typescript
 const engine = createPermissionEngine({
-  roles,
+  roles: [{ name: "staff", permissions: ["task:*"] }],
   policyTimeout: 250,
   policies: [
     {
       name: "business-hours",
-      permissions: ["post:*"], // wildcards work here too
+      permissions: ["task:*"], // wildcards work here too
       priority: 10, // higher runs first
       cacheable: false, // depends on the clock, so never cache it
-      evaluate: (context) =>
+      evaluate: () =>
         isBusinessHours()
-          ? { allowed: true }
+          ? { allowed: true } // "no objection" — the role still has to grant
           : { allowed: false, reason: "outside_business_hours" },
     },
   ],
 });
+
+await engine.can(staff, "task:delete"); // true in hours, false after
+await engine.can(guest, "task:delete"); // false: no role grants it
 ```
 
+> **Warning — a policy's `allowed: true` is not a grant.** Before 1.4 it was:
+> an allowing policy granted the permission even to an actor with no roles, so
+> the "business-hours" policy above handed `task:delete` to everyone during
+> office hours. A policy now only constrains, unless it opts in with
+> `effect: "grant"`.
+
 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 decide, but never overrides
-a denial — from another policy or from a deny rule that applied.
+that throws, or exceeds `policyTimeout`, denies. A denying policy always wins.
+An allowing policy grants nothing by itself: the actor's roles, direct
+permissions or rules must still grant the permission.
+
+### Policies that grant
+
+A policy that establishes the right on its own — ownership is the usual one —
+says so with `effect: "grant"`:
+
+```typescript
+const engine = createPermissionEngine({
+  roles,
+  policies: [
+    {
+      name: "author-can-edit",
+      permissions: ["post:update"],
+      effect: "grant", // an allow here grants, even with no role
+      evaluate: ({ actor, resource }) => ({
+        allowed: (resource as { authorId?: string })?.authorId === actor.id,
+      }),
+    },
+  ],
+});
+```
+
+A granting policy still never overrides a denial — from another policy, an
+explicit deny, or a deny rule that applied. Only the exact value `"grant"`
+grants; a typo constrains. `createPermissionEngine({ defaultPolicyEffect:
+"grant" })` restores the pre-1.4 behaviour for every policy that sets no
+`effect` — prefer marking the individual policies.
 
 `policyTimeout: 0` means "expire immediately", not "no timeout" — omit it to
 disable.
@@ -202,7 +268,11 @@ roles.define({ name: "auditor", permissions: ["audit:read"] });
 roles.remove("reader");
 // both take effect on the next check: the engine subscribes to the registry
 
-policies.define({ name: "lockdown", permissions: ["*:*"], evaluate: () => ({ allowed: false }) });
+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
@@ -233,11 +303,17 @@ permissions.define("post:write", { implies: ["post:read"] });
 
 const engine = createPermissionEngine({
   roles,
-  expandImplied: (permission) => permissions.expandImplied(permission),
+  expandImplied: permissions,
 });
 // An actor granted post:admin now passes post:read.
 ```
 
+Pass the registry itself rather than a closure over it. The engine subscribes
+to it, so `permissions.remove("post:admin")` — or redefining it without the
+implication — drops the decisions that were cached while it stood. A bare
+`(permission) => permissions.expandImplied(permission)` still works, but it
+cannot announce a change, so an engine given one caches no decisions at all.
+
 ## Caching
 
 ```typescript
@@ -278,6 +354,12 @@ A check is cached only when the key can describe it completely:
   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;
+- an engine with a `roleResolver` or `permissionResolver` and no
+  `resolverCacheKey` caches **nothing**: the resolver reads state the key
+  cannot describe, so an entry would outlive a grant withdrawn upstream;
+- an engine whose `expandImplied` is a bare function rather than a
+  `createPermissionRegistry()` caches **nothing**, for the same reason: a
+  revoked implication cannot announce itself;
 - a TTL of `0` or less means "do not cache".
 
 `deniedPermissions` is evaluated before the cache is consulted, so a deny
@@ -298,22 +380,40 @@ const engine = createPermissionEngine({
 A resolver that fails is reported through `onError` and the check continues
 fail-closed, rather than throwing out of the authorization path.
 
+A resolver reads authorization state the engine does not own and cannot see
+change, and none of it is in the decision-cache key. **A resolver-backed
+engine therefore caches nothing** unless you describe that state with
+`resolverCacheKey`:
+
+```typescript
+const engine = createPermissionEngine({
+  roles,
+  cache: createMemoryPermissionCache(),
+  permissionResolver: { resolvePermissions: (actor) => db.rulesFor(actor.id) },
+  // Anything that changes when the resolver's answer could change.
+  resolverCacheKey: (actor) => db.grantsVersionFor(actor.id),
+});
+```
+
+Return `undefined` for an actor whose state you cannot describe, and that
+actor's decisions stay uncached.
+
 ## 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"`                 |
-| 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`                          |
-| `signal` aborted            | throws `AuthorizationAbortedError`                     |
+| Situation                     | Result                                                 |
+| ----------------------------- | ------------------------------------------------------ |
+| Unknown role on the actor     | denied; reported to `onError`; other roles still apply |
+| Malformed permission string   | denied, `reason: "invalid_permission"`                 |
+| 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`                          |
+| `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
@@ -380,7 +480,8 @@ const guard = authorize(engine, "post:update", {
   extractResource: (context) => loadPost(context.request.getParam?.("id")),
   // The tenant @zudojs/tenancy resolved and trust-checked — never a header.
   extractMetadata: (context) => ({
-    tenantId: context.state.get<{ tenantId: string }>("tenancy:context")?.tenantId,
+    tenantId: context.state.get<{ tenantId: string }>("tenancy:context")
+      ?.tenantId,
   }),
   onError: (error, source) => logger.warn({ error, source }, "guard denied"),
 });
@@ -389,7 +490,11 @@ const guard = authorize(engine, "post:update", {
 - 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**.
+  **403**. The refusal is a `GuardResponse` (`createGuardResponse` from
+  `@zudojs/middleware`), which `@zudojs/http` sends with that status, body and
+  headers. It used to be a plain `{ status, body, headers }` object, which a
+  route middleware's return ignored: the handler did not run, but the client
+  got `200`.
 - 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
@@ -405,7 +510,18 @@ const guard = authorize(engine, "post:update", {
 
 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).
+query may be plain objects, as `@zudojs/http` provides them, or maps), and
+`HttpMiddleware` is assignable to `@zudojs/http`'s own `HttpMiddleware` — pass
+a guard straight to a route, no `as never`:
+
+```typescript
+router.put("/posts/:id", updatePost, { middleware: [guard] });
+```
+
+A middleware of your own typed as this package's `HttpMiddleware` answers a
+refusal with `createGuardResponse({ status, body })`; returning a plain
+`{ status, body, headers }` object is no longer typed, because
+`@zudojs/http` never sent it as a response.
 
 ## Errors
 

package/dist/evaluator/authorizationEngine.d.ts

@@ -3,7 +3,7 @@
  *
  * @module evaluator/authorizationEngine
  */
-import type { PermissionActor, PermissionDecision, ExplainResult, PermissionRule, PermissionPolicyDefinition, PermissionCache, PermissionResolver, RoleResolver, RoleDefinition, RuleCombiningAlgorithm, AuthorizationOptions } from "../permissionTypes/index.js";
+import type { PermissionActor, PermissionDecision, ExplainResult, PermissionRule, PermissionPolicyDefinition, PolicyEffect, 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";
 /**
@@ -28,6 +28,19 @@ export interface PolicySource {
     get(name: string): PermissionPolicyDefinition | undefined;
     subscribe?(listener: () => void): () => void;
 }
+/**
+ * Anything the engine will accept as its source of permission implications.
+ *
+ * A source with `subscribe` (every `createPermissionRegistry()`) is watched
+ * like the role and policy registries: revoking an implication drops every
+ * decision that was cached while it stood. A bare function cannot announce a
+ * change, so an engine given one caches nothing — see
+ * {@link PermissionEngineOptions.expandImplied}.
+ */
+export interface ImpliedPermissionSource {
+    expandImplied(permission: string): readonly string[];
+    subscribe?(listener: () => void): () => void;
+}
 /** Configuration for the permission engine. */
 export interface PermissionEngineOptions {
     /**
@@ -44,6 +57,16 @@ export interface PermissionEngineOptions {
     readonly rules?: readonly PermissionRule[];
     /** Default timeout for async policy evaluation (ms). */
     readonly policyTimeout?: number;
+    /**
+     * Effect of a policy that sets no `effect` of its own. Default:
+     * `"constrain"` — an allowing policy is an extra condition and cannot
+     * grant a permission the actor's roles, permissions or rules do not.
+     *
+     * `"grant"` restores the behaviour before 1.4, where every allowing policy
+     * was an independent grant. Prefer `effect: "grant"` on the individual
+     * policies that really establish the right on their own.
+     */
+    readonly defaultPolicyEffect?: PolicyEffect;
     /** How competing rules combine. Default: `"deny-overrides"`. */
     readonly algorithm?: RuleCombiningAlgorithm;
     /** Caches decisions. Create one with `createMemoryPermissionCache()`. */
@@ -54,8 +77,31 @@ export interface PermissionEngineOptions {
     readonly permissionResolver?: PermissionResolver;
     /** Loads additional roles for an actor from an external source. */
     readonly roleResolver?: RoleResolver;
-    /** Expands a permission into the permissions it implies. */
-    readonly expandImplied?: (permission: string) => readonly string[];
+    /**
+     * Describes the state a resolver is answering from, so that decisions it
+     * influenced can be cached safely.
+     *
+     * A resolver reads authorization data the engine does not own and cannot
+     * see change — a grants table, another service. Nothing about it is in the
+     * decision-cache key, so an entry written while the resolver said "allow"
+     * kept answering after the grant was withdrawn upstream. Resolver-backed
+     * engines therefore **do not cache at all** unless this is supplied.
+     *
+     * Return a value that changes whenever the resolver's answer for this actor
+     * could change — a version column, an `updatedAt` stamp, a grants-table
+     * generation. Return `undefined` for an actor whose state cannot be
+     * described, and that actor's decisions stay uncached.
+     */
+    readonly resolverCacheKey?: (actor: PermissionActor) => string | undefined;
+    /**
+     * Expands a permission into the permissions it implies.
+     *
+     * Prefer passing a `createPermissionRegistry()` — the engine subscribes to
+     * it, so revoking an implication invalidates the decisions cached under it.
+     * A bare function cannot announce a change, so an engine given one caches
+     * no decisions rather than serving one from a revoked implication.
+     */
+    readonly expandImplied?: ((permission: string) => readonly string[]) | ImpliedPermissionSource;
     /** Emits an event for every completed check, including failures. */
     readonly emitter?: PermissionEventEmitter;
     /** Reports a failure authorization swallowed to stay fail-closed. */

package/dist/evaluator/authorizationEngine.js

@@ -20,6 +20,11 @@ function isPolicySource(policies) {
         !Array.isArray(policies) &&
         typeof policies.names === "function");
 }
+function isImpliedPermissionSource(source) {
+    return (source !== undefined &&
+        typeof source !== "function" &&
+        typeof source.expandImplied === "function");
+}
 /**
  * Create a permission engine.
  */
@@ -99,6 +104,34 @@ export function createPermissionEngine(options) {
         options.roles.subscribe?.(invalidateConfiguration);
     }
     policySource?.subscribe?.(invalidateConfiguration);
+    // The third registry the README wires in. Without this, revoking an
+    // implication left every decision it granted in the cache for the full TTL
+    // — `skipCache: true` said "deny" while `can()` kept saying "allow".
+    const impliedSource = isImpliedPermissionSource(options?.expandImplied)
+        ? options.expandImplied
+        : undefined;
+    const expandImplied = impliedSource
+        ? (permission) => impliedSource.expandImplied(permission)
+        : options?.expandImplied;
+    const impliedWatched = impliedSource?.subscribe?.(invalidateConfiguration) !== undefined;
+    // Two inputs the cache key cannot describe. An implication source that
+    // cannot announce a change, and a resolver reading state the engine does
+    // not own, both make a cached allow outlive the grant behind it — so the
+    // decision is not cached at all unless the caller closes the gap.
+    const impliedUnwatched = expandImplied !== undefined && !impliedWatched;
+    const resolverConfigured = options?.permissionResolver !== undefined ||
+        options?.roleResolver !== undefined;
+    const resolverCacheKey = options?.resolverCacheKey;
+    const cacheScope = (actor) => {
+        if (impliedUnwatched)
+            return undefined;
+        if (!resolverConfigured)
+            return `g${generation}`;
+        if (!resolverCacheKey)
+            return undefined;
+        const scope = resolverCacheKey(actor);
+        return scope === undefined ? undefined : `g${generation}|r${scope}`;
+    };
     // One live view over the configuration. `policies` is a getter so a
     // registry-backed engine re-reads the registry on every evaluation — an
     // Ability used to capture a snapshot of the policy list when it was
@@ -111,14 +144,15 @@ export function createPermissionEngine(options) {
         },
         rules: options?.rules,
         policyTimeout: options?.policyTimeout,
+        defaultPolicyEffect: options?.defaultPolicyEffect,
         algorithm: options?.algorithm,
         cache: options?.cache,
         cacheTtlMs: options?.cacheTtlMs,
         permissionResolver: options?.permissionResolver,
         roleResolver: options?.roleResolver,
-        expandImplied: options?.expandImplied,
+        expandImplied,
         onError: options?.onError,
-        cacheScope: () => `g${generation}`,
+        cacheScope,
     };
     const evaluatorOptions = () => liveOptions;
     const emitter = options?.emitter;

package/dist/evaluator/engineSupport/evaluator.cacheKey.d.ts

@@ -19,6 +19,10 @@ import type { EvaluatorOptions } from "../evaluator.pipeline.js";
  *   in the key as a digest; an actor the digest cannot describe is not cached.
  * - The engine's configuration generation is in the key, so a role removed
  *   from a live registry cannot be served from an entry written before.
+ * - An external resolver reads state the key knows nothing about, so a
+ *   resolver-backed engine is uncacheable unless it supplies
+ *   `resolverCacheKey`. So is one whose implication source cannot announce a
+ *   change.
  */
 export declare function decisionCacheKey(actor: PermissionActor, permissionStr: string, resource: unknown, options: EvaluatorOptions, authOptions?: AuthorizationOptions): string | undefined;
 //# sourceMappingURL=evaluator.cacheKey.d.ts.map

package/dist/evaluator/engineSupport/evaluator.cacheKey.js

@@ -38,6 +38,10 @@ function resourceIdOf(resource) {
  *   in the key as a digest; an actor the digest cannot describe is not cached.
  * - The engine's configuration generation is in the key, so a role removed
  *   from a live registry cannot be served from an entry written before.
+ * - An external resolver reads state the key knows nothing about, so a
+ *   resolver-backed engine is uncacheable unless it supplies
+ *   `resolverCacheKey`. So is one whose implication source cannot announce a
+ *   change.
  */
 export function decisionCacheKey(actor, permissionStr, resource, options, authOptions) {
     if (!options.cache || authOptions?.skipCache === true)
@@ -50,7 +54,17 @@ export function decisionCacheKey(actor, permissionStr, resource, options, authOp
     const digest = actorCacheDigest(actor);
     if (digest === undefined)
         return undefined;
-    const generation = options.cacheScope?.() ?? "";
+    // An engine that cannot describe its own configuration for this actor
+    // returns `undefined` here — an external resolver with no
+    // `resolverCacheKey`, or an implication source that cannot announce a
+    // change. Both would otherwise keep answering from a revoked grant.
+    let generation = "";
+    if (options.cacheScope !== undefined) {
+        const scope = options.cacheScope(actor);
+        if (scope === undefined)
+            return undefined;
+        generation = scope;
+    }
     return permissionCacheKey(actor.id, permissionStr, resourceId, `${generation}${digest}`);
 }
 //# sourceMappingURL=evaluator.cacheKey.js.map

package/dist/evaluator/evaluator.core.js

@@ -185,7 +185,7 @@ export async function evaluate(actor, permissionStr, resource, options, authOpti
             });
         }
     }
-    const decision = combine(ruleResult, outcome.decision, permissionStr);
+    const decision = combine(ruleResult, outcome.decision, outcome.grants, permissionStr);
     /* ── Cache write ─────────────────────────────────────────────────────── */
     // A decision forced by a condition that threw describes the failure, not
     // the actor, and must not outlive it.
@@ -204,15 +204,18 @@ export async function evaluate(actor, permissionStr, resource, options, authOpti
 /**
  * Combine the rule outcome with the policy outcome.
  *
- * A denying policy always wins. An allowing policy can grant access the rules
- * did not, which is what makes a policy an ABAC escape hatch rather than a
- * filter — but it can never override a denial, and that includes a denial
- * the *rules* produced. "The rules did not allow" covers two cases: no rule
- * matched, and a deny rule matched. Treating them alike let an allowing
- * policy for `post:*` cancel a `deny post:update` rule — the exact inversion
- * of `deny-overrides`.
+ * A denying policy always wins. An allowing policy is, by default, only an
+ * extra condition: the actor's roles, permissions or rules must still grant
+ * the permission. It used to grant on its own, so a "business-hours" policy
+ * handed `task:delete` to an actor with no roles at all. Only a policy with
+ * `effect: "grant"` (or an engine with `defaultPolicyEffect: "grant"`) can
+ * grant access the rules did not — and even then it never overrides a
+ * denial, including one the *rules* produced. "The rules did not allow"
+ * covers two cases: no rule matched, and a deny rule matched. Treating them
+ * alike let an allowing policy for `post:*` cancel a `deny post:update` rule
+ * — the exact inversion of `deny-overrides`.
  */
-function combine(ruleResult, policyDecision, permissionStr) {
+function combine(ruleResult, policyDecision, policyGrants, permissionStr) {
     if (policyDecision && !policyDecision.allowed)
         return policyDecision;
     const denyRule = !ruleResult.allowed && ruleResult.matchedRule?.effect === "deny"
@@ -232,7 +235,7 @@ function combine(ruleResult, policyDecision, permissionStr) {
             ...(policyDecision?.policy ? { policy: policyDecision.policy } : {}),
         });
     }
-    if (policyDecision?.allowed)
+    if (policyDecision?.allowed && policyGrants)
         return policyDecision;
     return denied("no_matching_rule");
 }

package/dist/evaluator/evaluator.pipeline.d.ts

@@ -3,7 +3,7 @@
  *
  * @module evaluator/evaluator.pipeline
  */
-import type { PermissionActor, PermissionContext, PermissionDecision, PermissionPolicyDefinition, PermissionRule, PermissionCache, PermissionResolver, RoleDefinition, RoleResolver, RuleCombiningAlgorithm, AuthorizationOptions } from "../permissionTypes/index.js";
+import type { PermissionActor, PermissionContext, PermissionDecision, PermissionPolicyDefinition, PermissionRule, PermissionCache, PermissionResolver, RoleDefinition, RoleResolver, RuleCombiningAlgorithm, AuthorizationOptions, PolicyEffect } from "../permissionTypes/index.js";
 /** Configuration for the evaluator. */
 export interface EvaluatorOptions {
     /** Function to look up a role definition by name. */
@@ -14,6 +14,8 @@ export interface EvaluatorOptions {
     readonly rules?: readonly PermissionRule[];
     /** Default timeout for async policy evaluation (ms). */
     readonly policyTimeout?: number;
+    /** Effect of a policy that sets none. Default: `"constrain"`. */
+    readonly defaultPolicyEffect?: PolicyEffect;
     /** How competing rules combine. Default: `"deny-overrides"`. */
     readonly algorithm?: RuleCombiningAlgorithm;
     /** Decision cache. */
@@ -35,8 +37,13 @@ export interface EvaluatorOptions {
      * Extra decision-cache key scope, read on every evaluation. The engine
      * passes its configuration generation, so a role change invalidates every
      * entry written before it.
+     *
+     * Returning `undefined` means this decision must not be cached: the engine
+     * uses that for the inputs the key cannot describe — an implication source
+     * that cannot announce a change, and an external resolver with no
+     * `resolverCacheKey`.
      */
-    readonly cacheScope?: () => string;
+    readonly cacheScope?: (actor: PermissionActor) => string | undefined;
 }
 /** The permissions and rules an actor holds, once everything is resolved. */
 export interface ResolvedGrants {
@@ -75,6 +82,13 @@ export interface PolicyOutcome {
     /** Whether every policy that ran allows the result to be cached. */
     readonly cacheable: boolean;
     readonly evaluated: readonly string[];
+    /**
+     * Whether the allow may grant on its own: every applicable policy allowed
+     * and at least one of them has the `"grant"` effect. `false` for a denial,
+     * and for an allow from constraining policies only, which then needs a
+     * role, permission or rule to grant.
+     */
+    readonly grants: boolean;
 }
 /**
  * Evaluate policies for a context.

package/dist/evaluator/evaluator.pipeline.js

@@ -3,6 +3,7 @@
  *
  * @module evaluator/evaluator.pipeline
  */
+import { policyGrants } from "../policy/policyEffect.core.js";
 import { resolveRolePermissions } from "../role/roleHierarchy.js";
 import { matches, permissionsOverlap, parsePermissionSafe, } from "../permission/permission.core.js";
 import { isWildcardTarget } from "../rule/rule.pattern.js";
@@ -153,13 +154,13 @@ function narrowerPolicies(policies, applicable, permissionStr) {
  */
 export async function evaluatePolicies(context, policies, options, authOptions) {
     if (policies.length === 0) {
-        return { decision: null, cacheable: true, evaluated: [] };
+        return { decision: null, cacheable: true, evaluated: [], grants: false };
     }
     const permissionStr = `${context.permission.resource}:${context.permission.action}`;
     const applicable = selectPolicies(policies, permissionStr);
     const denyOnly = narrowerPolicies(policies, applicable, permissionStr);
     if (applicable.length === 0 && denyOnly.length === 0) {
-        return { decision: null, cacheable: true, evaluated: [] };
+        return { decision: null, cacheable: true, evaluated: [], grants: false };
     }
     // The per-call timeout wins, but the engine-level default is what makes a
     // configured timeout mean anything at all.
@@ -183,6 +184,7 @@ export async function evaluatePolicies(context, policies, options, authOptions)
                     }),
                     cacheable,
                     evaluated,
+                    grants: false,
                 };
             }
         }
@@ -200,20 +202,23 @@ export async function evaluatePolicies(context, policies, options, authOptions)
                 }),
                 cacheable: false,
                 evaluated,
+                grants: false,
             };
         }
     }
     if (applicable.length === 0) {
-        return { decision: null, cacheable, evaluated };
+        return { decision: null, cacheable, evaluated, grants: false };
     }
+    const grants = applicable.some((policy) => policyGrants(policy, options.defaultPolicyEffect));
     return {
         decision: Object.freeze({
             allowed: true,
-            reason: "policy_allow",
+            reason: grants ? "policy_allow" : "policy_pass",
             policy: applicable.map((policy) => policy.name).join(","),
         }),
         cacheable,
         evaluated,
+        grants,
     };
 }
 /**

package/dist/http/httpHelpers.d.ts

@@ -3,6 +3,7 @@
  *
  * @module http/httpHelpers
  */
+import { type GuardResponse } from "@zudojs/middleware";
 import type { PermissionDecision } from "../permissionTypes/index.js";
 /** Options for creating denied responses. */
 export interface DeniedResponseOptions {
@@ -16,12 +17,12 @@ export interface DeniedResponseOptions {
     /** Value for the `WWW-Authenticate` header on a 401. */
     readonly authenticateChallenge?: string;
 }
-/** A framework-agnostic response. */
-export interface PermissionHttpResponse {
-    readonly status: number;
-    readonly body: unknown;
-    readonly headers: Readonly<Record<string, string>>;
-}
+/**
+ * A framework-agnostic response: a `GuardResponse` from `@zudojs/middleware`,
+ * which `@zudojs/http` sends with its own status. It still has the
+ * `status`, `body` and `headers` fields this type always had.
+ */
+export type PermissionHttpResponse = GuardResponse;
 /**
  * Create a 403 Forbidden JSON response for a decision.
  *

package/dist/http/httpHelpers.js

@@ -3,6 +3,7 @@
  *
  * @module http/httpHelpers
  */
+import { createGuardResponse } from "@zudojs/middleware";
 const JSON_HEADERS = { "content-type": "application/json" };
 /**
  * Create a 403 Forbidden JSON response for a decision.
@@ -18,11 +19,7 @@ export function createForbiddenResponse(decision, options) {
             error: "Forbidden",
             message: decision.publicReason ?? "Access denied",
         };
-    return Object.freeze({
-        status: 403,
-        body,
-        headers: JSON_HEADERS,
-    });
+    return createGuardResponse({ status: 403, body, headers: JSON_HEADERS });
 }
 /**
  * Create a 401 Unauthorized JSON response.
@@ -34,23 +31,19 @@ export function createUnauthorizedResponse(options) {
     const body = options?.unauthenticatedResponse
         ? options.unauthenticatedResponse()
         : { error: "Unauthorized", message: "Authentication required" };
-    return Object.freeze({
+    return createGuardResponse({
         status: 401,
         body,
-        headers: Object.freeze({
+        headers: {
             ...JSON_HEADERS,
             "www-authenticate": options?.authenticateChallenge ?? "Bearer",
-        }),
+        },
     });
 }
 /**
  * Create a JSON response.
  */
 export function createJsonResponse(status, body) {
-    return Object.freeze({
-        status,
-        body,
-        headers: JSON_HEADERS,
-    });
+    return createGuardResponse({ status, body, headers: JSON_HEADERS });
 }
 //# sourceMappingURL=httpHelpers.js.map

package/dist/http/httpTypes.d.ts

@@ -6,8 +6,23 @@
  *
  * @module http/httpTypes
  */
-/** HTTP middleware signature from @zudojs/http. */
-export type HttpMiddleware = (context: HttpMiddlewareContext, next: () => Promise<HttpResponseContext>) => void | Response | HttpResponseContext | Promise<void | Response | HttpResponseContext>;
+import type { GuardResponse } from "@zudojs/middleware";
+/**
+ * What a permission middleware returns: nothing, a web `Response`, a
+ * `GuardResponse` refusing the request, or whatever `next()` produced.
+ */
+export type HttpMiddlewareOutcome<Downstream> = void | Response | GuardResponse | Downstream;
+/**
+ * HTTP middleware signature, structurally assignable to `@zudojs/http`'s
+ * `HttpMiddleware` without a cast.
+ *
+ * Generic over what `next()` resolves to, so a middleware hands back the
+ * real pipeline's response unchanged. A refusal is a `GuardResponse`
+ * (`createGuardResponse` from `@zudojs/middleware`), which `@zudojs/http`
+ * sends with its own status; a plain `{ status, body, headers }` object is
+ * not a response.
+ */
+export type HttpMiddleware = <Downstream extends HttpResponseContext>(context: HttpMiddlewareContext, next: () => Promise<Downstream>) => HttpMiddlewareOutcome<Downstream> | Promise<HttpMiddlewareOutcome<Downstream>>;
 /** HTTP middleware context from @zudojs/http. */
 export interface HttpMiddlewareContext {
     readonly request: HttpRequestContext;

package/dist/http/index.d.ts

@@ -13,5 +13,5 @@
 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 { loadResource, RESOURCE_ERROR_DECISION, type ResourceExtractor, type ResourceOutcome, } from "./httpResource.helper.js";
-export type { HttpRequestBag, HttpMiddleware, HttpMiddlewareContext, HttpRequestContext, HttpResponseContext, HttpMiddlewareState, } from "./httpTypes.js";
+export type { HttpRequestBag, HttpMiddleware, HttpMiddlewareOutcome, HttpMiddlewareContext, HttpRequestContext, HttpResponseContext, HttpMiddlewareState, } from "./httpTypes.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/permission/permissionRegistry.d.ts

@@ -39,6 +39,16 @@ export interface PermissionRegistry {
     expandImplied(permission: string): readonly string[];
     remove(permission: string): boolean;
     clear(): void;
+    /**
+     * Be told whenever the permission set changes (`define`, a `remove` that
+     * removed something, `clear`). Returns an unsubscribe function.
+     *
+     * An engine given this registry as its `expandImplied` source subscribes
+     * itself, which is what makes revoking an implication take effect
+     * immediately: the engine's cached decisions were written under the old
+     * implication and would otherwise keep granting for the whole TTL.
+     */
+    subscribe(listener: () => void): () => void;
 }
 /**
  * Create a permission registry.
@@ -49,7 +59,10 @@ export interface PermissionRegistry {
  *
  * const engine = createPermissionEngine({
  *   roles,
- *   expandImplied: (permission) => permissions.expandImplied(permission),
+ *   // Pass the registry itself, not a closure over it: the engine
+ *   // subscribes, so revoking an implication drops the cached decisions
+ *   // that were made under it.
+ *   expandImplied: permissions,
  * });
  * ```
  */

package/dist/permission/permissionRegistry.js

@@ -4,6 +4,7 @@
  * @module permission/permissionRegistry
  */
 import { DuplicatePermissionError, InvalidPermissionError, PermissionNotFoundError, } from "../permissionErrors/index.js";
+import { createChangeNotifier } from "../utils/utils.notifier.js";
 import { formatPermission, isValidPermission, matchesPermission, parsePermission, } from "./permission.core.js";
 /**
  * Create a permission registry.
@@ -14,13 +15,17 @@ import { formatPermission, isValidPermission, matchesPermission, parsePermission
  *
  * const engine = createPermissionEngine({
  *   roles,
- *   expandImplied: (permission) => permissions.expandImplied(permission),
+ *   // Pass the registry itself, not a closure over it: the engine
+ *   // subscribes, so revoking an implication drops the cached decisions
+ *   // that were made under it.
+ *   expandImplied: permissions,
  * });
  * ```
  */
 export function createPermissionRegistry(options) {
     const permissions = new Map();
     const allowOverride = options?.allowOverride ?? false;
+    const changes = createChangeNotifier();
     function keyOf(permission) {
         if (typeof permission === "string") {
             // Validate strings and structured values alike; a structured value
@@ -53,6 +58,7 @@ export function createPermissionRegistry(options) {
                     ? Object.freeze([...defineOptions.implies])
                     : undefined,
             });
+            changes.notify();
         },
         get(permission) {
             return permissions.get(permission)?.parsed;
@@ -96,10 +102,17 @@ export function createPermissionRegistry(options) {
             return [...expanded];
         },
         remove(permission) {
-            return permissions.delete(permission);
+            const removed = permissions.delete(permission);
+            if (removed)
+                changes.notify();
+            return removed;
         },
         clear() {
             permissions.clear();
+            changes.notify();
+        },
+        subscribe(listener) {
+            return changes.subscribe(listener);
         },
     };
 }

package/dist/permissionTypes/index.d.ts

@@ -5,5 +5,5 @@
  */
 export { type PermissionActor, type Permission, type PermissionString, } from "./permissionActor.js";
 export { type RuleEffect, type RuleCombiningAlgorithm, type RuleEvaluation, type PermissionRule, type PermissionConditionFn, type PermissionContext, type PermissionDecision, } from "./ruleTypes.js";
-export { type RoleDefinition, type PermissionResolver, type RoleResolver, type PermissionCache, type PermissionPolicyDefinition, type ExplainStep, type ExplainResult, type AuthorizationOptions, } from "./policyTypes.js";
+export { type RoleDefinition, type PermissionResolver, type RoleResolver, type PermissionCache, type PermissionPolicyDefinition, type PolicyEffect, type ExplainStep, type ExplainResult, type AuthorizationOptions, } from "./policyTypes.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/permissionTypes/policyTypes.d.ts

@@ -42,9 +42,27 @@ export interface PermissionCache {
     /** Drops every entry. */
     clear?(): Promise<void>;
 }
+/**
+ * What an allowing policy means.
+ *
+ * - `"constrain"` (the default): the policy is an extra condition on top of
+ *   RBAC/ABAC. Its allow means "no objection"; the actor's roles, direct
+ *   permissions or rules must still grant the permission. Its deny denies.
+ * - `"grant"`: the policy is an independent grant. Its allow grants the
+ *   permission even when no role or rule does — an ownership check, say.
+ *   Use it only for a policy that establishes the right on its own.
+ */
+export type PolicyEffect = "constrain" | "grant";
 /** A named authorization policy. */
 export interface PermissionPolicyDefinition {
     readonly name: string;
+    /**
+     * Whether this policy's allow can grant a permission the actor's roles do
+     * not include. Default: the engine's `defaultPolicyEffect`, which is
+     * `"constrain"` — a policy only ever narrows access. Any value other than
+     * `"grant"` constrains.
+     */
+    readonly effect?: PolicyEffect;
     /**
      * Permissions this policy applies to. Wildcards are honoured, so
      * `["post:*"]` covers `post:update` — the same matching grants use.

package/dist/policy/index.d.ts

@@ -4,4 +4,5 @@
  * @module policy
  */
 export { createPolicyRegistry, type PolicyRegistry, type PolicyRegistryOptions, } from "./policyRegistry.js";
+export { DEFAULT_POLICY_EFFECT, policyGrants } from "./policyEffect.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/policy/index.js

@@ -4,4 +4,5 @@
  * @module policy
  */
 export { createPolicyRegistry, } from "./policyRegistry.js";
+export { DEFAULT_POLICY_EFFECT, policyGrants } from "./policyEffect.core.js";
 //# sourceMappingURL=index.js.map

package/dist/policy/policyEffect.core.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Policy effect resolution: whether an allowing policy may grant access on
+ * its own or only constrains what RBAC/ABAC already granted.
+ *
+ * @module policy/policyEffect.core
+ */
+import type { PermissionPolicyDefinition, PolicyEffect } from "../permissionTypes/index.js";
+/** The effect a policy without its own `effect` has. */
+export declare const DEFAULT_POLICY_EFFECT: PolicyEffect;
+/**
+ * Whether a policy's allow is an independent grant.
+ *
+ * Only the exact value `"grant"` grants. A typo, a missing value or anything
+ * else falls back to constraining, so a mistake narrows access instead of
+ * widening it.
+ *
+ * @param policy - The policy that allowed.
+ * @param defaultEffect - The engine's `defaultPolicyEffect`.
+ */
+export declare function policyGrants(policy: PermissionPolicyDefinition, defaultEffect?: PolicyEffect): boolean;
+//# sourceMappingURL=policyEffect.core.d.ts.map

package/dist/policy/policyEffect.core.js

@@ -0,0 +1,22 @@
+/**
+ * Policy effect resolution: whether an allowing policy may grant access on
+ * its own or only constrains what RBAC/ABAC already granted.
+ *
+ * @module policy/policyEffect.core
+ */
+/** The effect a policy without its own `effect` has. */
+export const DEFAULT_POLICY_EFFECT = "constrain";
+/**
+ * Whether a policy's allow is an independent grant.
+ *
+ * Only the exact value `"grant"` grants. A typo, a missing value or anything
+ * else falls back to constraining, so a mistake narrows access instead of
+ * widening it.
+ *
+ * @param policy - The policy that allowed.
+ * @param defaultEffect - The engine's `defaultPolicyEffect`.
+ */
+export function policyGrants(policy, defaultEffect = DEFAULT_POLICY_EFFECT) {
+    return (policy.effect ?? defaultEffect) === "grant";
+}
+//# sourceMappingURL=policyEffect.core.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/permissions",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Generic authorization engine with RBAC, ABAC, resource authorization, wildcards, role hierarchy, policies, and abilities.",
   "license": "MIT",
   "author": {
@@ -26,14 +26,15 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.1.0"
+    "@zudojs/errors": "1.3.0",
+    "@zudojs/middleware": "1.1.0"
   },
   "engines": {
     "node": ">=24.0.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "publishConfig": {
     "access": "public"
@@ -45,7 +46,7 @@
     "authorization",
     "permissions"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-permissions",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },