@zudojs/permissions 1.4.0 → 1.4.1

package/README.md

@@ -235,13 +235,29 @@ const engine = createPermissionEngine({
     },
   ],
 });
+
+await engine.can(author, "post:update", post); // true: the policy grants
+await engine.can(editor, "post:update", post); // true: the role grants
+await engine.can(viewer, "post:update", post); // false: neither does
 ```
 
+A granting policy **grants when it allows and abstains when it does not**
+(including when it throws or times out): it adds access, and never takes away
+what roles, direct permissions or rules grant. So the policy returns only the
+ownership test — no `|| actorHasRole(actor, "editor")` is needed to keep
+editors working. In 1.4.0 a granting policy's `allowed: false` denied, so an
+ownership policy locked out every editor who was not the author. To deny, use
+an explicit deny rule, `deniedPermissions`, or a constraining policy.
+
 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.
+grants; a typo constrains.
+
+`createPermissionEngine({ defaultPolicyEffect: "grant" })` restores the
+pre-1.4 behaviour, unchanged, for every policy that sets no `effect`: an
+allowing policy grants and a denying one denies. It exists for backward
+compatibility — prefer marking the individual policies with `effect: "grant"`,
+which abstain instead of denying even under that engine default.
 
 `policyTimeout: 0` means "expire immediately", not "no timeout" — omit it to
 disable.
@@ -508,6 +524,46 @@ const guard = authorize(engine, "post:update", {
   several permissions, short-circuiting on the first that decides the outcome.
   An empty list denies in either mode.
 
+### A resource that does not exist
+
+By default a guard checks the permission even when `extractResource` returns
+`undefined` or `null`, with no resource. Rules and policies that read the
+resource see nothing, so the answer comes from the rest of the model. A role
+that grants `post:update` lets the request through, and the handler still has
+to answer 404. A resource-owner rule denies with 403. `onMissingResource`
+moves that answer into the guard:
+
+```typescript
+const guard = authorize(engine, "post:update", {
+  extractActor: (context) => context.state.get("auth:user"),
+  extractResource: (context) => posts.find(context.request.getParam?.("id")),
+  onMissingResource: "notFound", // 404 when the loader returns undefined/null
+  notFoundResponse: () => ({ error: "Not Found" }), // optional body
+});
+```
+
+| `onMissingResource` | A missing resource answers |
+| ------------------- | -------------------------- |
+| `"check"` (default) | whatever the engine decides with no resource, as before |
+| `"forbid"`          | **403**, without evaluating |
+| `"notFound"`        | **404**, without evaluating |
+
+The option applies only to a guard that has an `extractResource`. An
+unauthenticated request still gets 401 first, and a loader that throws still
+gets 403. The guard records `RESOURCE_NOT_FOUND_DECISION`
+(`reason: "resource_not_found"`) under `permissions:decision`.
+`createRequirePermissionsMiddleware` takes the same two options. The 404 body
+is built by `createNotFoundResponse`.
+
+**The trade-off.** A 404 hides whether a resource exists only when every
+answer is consistent. With `"notFound"`, an authenticated caller who lacks the
+permission gets 404 for an id that does not exist and 403 for one that does,
+so the two statuses confirm which ids exist. To conceal existence from callers
+who are not authorised, every route over the resource must answer the same
+way, and a denial on an existing resource must also answer 404. These guards
+do not do that for you. Use `"notFound"` to take the lookup-and-404 out of the
+handler. On its own it does not conceal anything.
+
 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), and

package/dist/evaluator/authorizationEngine.d.ts

@@ -62,9 +62,11 @@ export interface PermissionEngineOptions {
      * `"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.
+     * `"grant"` restores the behaviour before 1.4 for every policy with no
+     * `effect`: an allowing policy is an independent grant and a denying one
+     * denies. Prefer `effect: "grant"` on the individual policies that really
+     * establish the right on their own — those grant on allow and abstain on
+     * deny, so they cannot take away what roles grant.
      */
     readonly defaultPolicyEffect?: PolicyEffect;
     /** How competing rules combine. Default: `"deny-overrides"`. */

package/dist/evaluator/evaluator.core.js

@@ -209,7 +209,9 @@ export async function evaluate(actor, permissionStr, resource, options, authOpti
  * 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
+ * grant access the rules did not. A per-policy `effect: "grant"` policy that
+ * does not allow abstains, so it never reaches here as a denial and cannot
+ * take away what the rules granted. A granting policy 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

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

@@ -83,10 +83,10 @@ export interface PolicyOutcome {
     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.
+     * Whether the allow may grant on its own: no policy denied and at least
+     * one granting policy allowed. `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;
 }
@@ -96,6 +96,12 @@ export interface PolicyOutcome {
  * Policies are evaluated highest priority first and short-circuit on the
  * first denial. A policy that throws or times out denies — an authorization
  * check that cannot complete must not fall through to "allowed".
+ *
+ * A policy with its own `effect: "grant"` only ever adds access: when it
+ * returns `allowed: false`, throws or times out it abstains, as if it had
+ * not applied, so an ownership policy cannot take away what the actor's
+ * roles grant. A constraining policy's denial, and a `"legacyGrant"`
+ * policy's (no `effect`, engine `defaultPolicyEffect: "grant"`), still deny.
  */
 export declare function evaluatePolicies(context: PermissionContext, policies: readonly PermissionPolicyDefinition[], options: EvaluatorOptions, authOptions?: AuthorizationOptions): Promise<PolicyOutcome>;
 /**

package/dist/evaluator/evaluator.pipeline.js

@@ -3,7 +3,7 @@
  *
  * @module evaluator/evaluator.pipeline
  */
-import { policyGrants } from "../policy/policyEffect.core.js";
+import { resolvePolicyMode } 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";
@@ -145,12 +145,27 @@ function narrowerPolicies(policies, applicable, permissionStr) {
         policy.permissions.some((pattern) => permissionsOverlap(pattern, permissionStr)))
         .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
 }
+/** A policy denial as the decision it produces. */
+function policyDenial(policy, reason, publicReason) {
+    return Object.freeze({
+        allowed: false,
+        reason,
+        policy: policy.name,
+        publicReason,
+    });
+}
 /**
  * Evaluate policies for a context.
  *
  * Policies are evaluated highest priority first and short-circuit on the
  * first denial. A policy that throws or times out denies — an authorization
  * check that cannot complete must not fall through to "allowed".
+ *
+ * A policy with its own `effect: "grant"` only ever adds access: when it
+ * returns `allowed: false`, throws or times out it abstains, as if it had
+ * not applied, so an ownership policy cannot take away what the actor's
+ * roles grant. A constraining policy's denial, and a `"legacyGrant"`
+ * policy's (no `effect`, engine `defaultPolicyEffect: "grant"`), still deny.
  */
 export async function evaluatePolicies(context, policies, options, authOptions) {
     if (policies.length === 0) {
@@ -166,55 +181,57 @@ export async function evaluatePolicies(context, policies, options, authOptions)
     // configured timeout mean anything at all.
     const timeoutMs = authOptions?.policyTimeout ?? options.policyTimeout;
     const evaluated = [];
+    const allowedBy = [];
     let cacheable = true;
+    let grants = false;
     for (const policy of [...applicable, ...denyOnly]) {
         assertNotAborted(context.signal ?? authOptions?.signal);
         evaluated.push(policy.name);
         if (policy.cacheable === false)
             cacheable = false;
+        const mode = resolvePolicyMode(policy, options.defaultPolicyEffect);
         try {
             const result = await withTimeout(Promise.resolve(policy.evaluate(context)), timeoutMs, policy.name);
             if (!result.allowed) {
+                if (mode === "grant")
+                    continue;
                 return {
-                    decision: Object.freeze({
-                        allowed: false,
-                        reason: result.reason ?? `policy:${policy.name}`,
-                        policy: policy.name,
-                        publicReason: result.publicReason ?? "Access denied",
-                    }),
+                    decision: policyDenial(policy, result.reason ?? `policy:${policy.name}`, result.publicReason ?? "Access denied"),
                     cacheable,
                     evaluated,
                     grants: false,
                 };
             }
+            if (applicable.includes(policy)) {
+                allowedBy.push(policy);
+                if (mode !== "constrain")
+                    grants = true;
+            }
         }
         catch (error) {
             if (error instanceof AuthorizationAbortedError)
                 throw error;
             options.onError?.(reportable(error, (cause) => new PolicyError(policy.name, cause)), `Policy.${policy.name}`);
+            cacheable = false;
+            if (mode === "grant")
+                continue;
             // Policy error — fail closed.
             return {
-                decision: Object.freeze({
-                    allowed: false,
-                    reason: `policy_error:${policy.name}`,
-                    policy: policy.name,
-                    publicReason: "Access denied",
-                }),
+                decision: policyDenial(policy, `policy_error:${policy.name}`, "Access denied"),
                 cacheable: false,
                 evaluated,
                 grants: false,
             };
         }
     }
-    if (applicable.length === 0) {
+    if (allowedBy.length === 0) {
         return { decision: null, cacheable, evaluated, grants: false };
     }
-    const grants = applicable.some((policy) => policyGrants(policy, options.defaultPolicyEffect));
     return {
         decision: Object.freeze({
             allowed: true,
             reason: grants ? "policy_allow" : "policy_pass",
-            policy: applicable.map((policy) => policy.name).join(","),
+            policy: allowedBy.map((policy) => policy.name).join(","),
         }),
         cacheable,
         evaluated,

package/dist/http/httpHelpers.d.ts

@@ -38,6 +38,16 @@ export declare function createForbiddenResponse(decision: PermissionDecision, op
  * leaves a client unable to tell "log in" from "you may not do this".
  */
 export declare function createUnauthorizedResponse(options?: DeniedResponseOptions): PermissionHttpResponse;
+/** Options for {@link createNotFoundResponse}. */
+export interface NotFoundResponseOptions {
+    /** Builds the 404 body for a resource that does not exist. */
+    readonly notFoundResponse?: () => unknown;
+}
+/**
+ * Create a 404 Not Found JSON response, for a guard whose resource loader
+ * found nothing (`onMissingResource: "notFound"`).
+ */
+export declare function createNotFoundResponse(options?: NotFoundResponseOptions): PermissionHttpResponse;
 /**
  * Create a JSON response.
  */

package/dist/http/httpHelpers.js

@@ -40,6 +40,16 @@ export function createUnauthorizedResponse(options) {
         },
     });
 }
+/**
+ * Create a 404 Not Found JSON response, for a guard whose resource loader
+ * found nothing (`onMissingResource: "notFound"`).
+ */
+export function createNotFoundResponse(options) {
+    const body = options?.notFoundResponse
+        ? options.notFoundResponse()
+        : { error: "Not Found", message: "Resource not found" };
+    return createGuardResponse({ status: 404, body, headers: JSON_HEADERS });
+}
 /**
  * Create a JSON response.
  */

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

@@ -10,7 +10,7 @@ import type { PermissionActor, AuthorizationOptions } from "../permissionTypes/i
 import type { PermissionEngine } from "../evaluator/authorizationEngine.js";
 import type { HttpMiddleware, HttpMiddlewareContext } from "./httpTypes.js";
 import { type DeniedResponseOptions } from "./httpHelpers.js";
-import { type ResourceExtractor } from "./httpResource.helper.js";
+import { type MissingResourceOptions, type ResourceExtractor } from "./httpResource.helper.js";
 /** Options shared by the permission middleware. */
 export interface AuthorizeMiddlewareOptions extends DeniedResponseOptions {
     /**
@@ -35,12 +35,13 @@ export interface AuthorizeMiddlewareOptions extends DeniedResponseOptions {
     readonly onError?: (error: unknown, source: string) => void;
 }
 /** Options for the requirePermission middleware. */
-export interface RequirePermissionMiddlewareOptions extends AuthorizeMiddlewareOptions {
+export interface RequirePermissionMiddlewareOptions extends AuthorizeMiddlewareOptions, MissingResourceOptions {
     /** The permission to check (e.g. "post:update"). */
     readonly permission: string;
     /**
      * Loads the resource the permission is checked against (optional). May be
      * async; it is awaited, and a loader that throws or rejects denies (403).
+     * What `undefined` or `null` answers is set by `onMissingResource`.
      */
     readonly extractResource?: ResourceExtractor;
 }
@@ -77,10 +78,11 @@ export declare function createRequirePermissionMiddleware(engine: PermissionEngi
  */
 export declare function authorize(engine: PermissionEngine, permission: string, options?: Omit<RequirePermissionMiddlewareOptions, "permission">): HttpMiddleware;
 /** Options for {@link createRequirePermissionsMiddleware}. */
-export interface RequirePermissionsMiddlewareOptions extends AuthorizeMiddlewareOptions {
+export interface RequirePermissionsMiddlewareOptions extends AuthorizeMiddlewareOptions, MissingResourceOptions {
     /**
      * Loads the resource checked for every permission (optional). May be
      * async; it is awaited, and a loader that throws or rejects denies (403).
+     * What `undefined` or `null` answers is set by `onMissingResource`.
      */
     readonly extractResource?: ResourceExtractor;
     /**

package/dist/http/httpMiddleware.core.js

@@ -7,7 +7,7 @@
  * @module http/httpMiddleware
  */
 import { createForbiddenResponse, createUnauthorizedResponse, } from "./httpHelpers.js";
-import { loadResource } from "./httpResource.helper.js";
+import { loadResource, refuseMissingResource, } from "./httpResource.helper.js";
 // ─── State Keys ───────────────────────────────────────────────────────────
 /** State key for the current actor. */
 export const ACTOR_STATE_KEY = "permissions:actor";
@@ -70,6 +70,11 @@ export function createRequirePermissionMiddleware(engine, options) {
             context.state.set(DECISION_STATE_KEY, loaded.decision);
             return createForbiddenResponse(loaded.decision, options);
         }
+        const missing = refuseMissingResource(options.extractResource, loaded.resource, options);
+        if (missing) {
+            context.state.set(DECISION_STATE_KEY, missing.decision);
+            return missing.response;
+        }
         const decision = await engine.check(actor, options.permission, loaded.resource, buildAuthorization(context, options));
         context.state.set(DECISION_STATE_KEY, decision);
         if (!decision.allowed)
@@ -107,6 +112,9 @@ export function createRequirePermissionsMiddleware(engine, permissions, options
         const loaded = await loadResource(context, options.extractResource, options.onError);
         if (!loaded.ok)
             return createForbiddenResponse(loaded.decision, options);
+        const missing = refuseMissingResource(options.extractResource, loaded.resource, options);
+        if (missing)
+            return missing.response;
         const resource = loaded.resource;
         const authorization = buildAuthorization(context, options);
         const results = new Map();

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

@@ -5,6 +5,7 @@
  */
 import type { PermissionDecision } from "../permissionTypes/index.js";
 import type { HttpMiddlewareContext } from "./httpTypes.js";
+import { type DeniedResponseOptions, type NotFoundResponseOptions, type PermissionHttpResponse } from "./httpHelpers.js";
 /** Loads the resource a permission is checked against. May be async. */
 export type ResourceExtractor = (context: HttpMiddlewareContext) => unknown | Promise<unknown>;
 /** The resource, or the denial to answer with when it could not be loaded. */
@@ -27,4 +28,46 @@ export declare const RESOURCE_ERROR_DECISION: PermissionDecision;
  * loader that throws or rejects now denies; the error goes to `onError`.
  */
 export declare function loadResource(context: HttpMiddlewareContext, extract: ResourceExtractor | undefined, onError?: (error: unknown, source: string) => void): Promise<ResourceOutcome>;
+/**
+ * What a guard does when `extractResource` returns `undefined` or `null`.
+ *
+ * - `"check"` (default): evaluate the permission with no resource, as the
+ *   guards always have. Rules and policies that read the resource see
+ *   nothing, so the answer depends on the rest of the model: a role grant
+ *   alone lets the request through to the handler.
+ * - `"forbid"`: answer 403 without evaluating.
+ * - `"notFound"`: answer 404 without evaluating.
+ */
+export type MissingResourceMode = "check" | "forbid" | "notFound";
+/**
+ * Options for a guard with a resource loader.
+ *
+ * A 404 for a missing resource hides nothing on its own. An authenticated
+ * caller who lacks the permission still gets 404 for an id that does not
+ * exist and 403 for one that does, so the pair of statuses confirms which
+ * ids exist. It conceals existence only when it is used consistently: every
+ * route over the resource answers the same way, and a denial on an existing
+ * resource is also answered 404 (not something these guards do for you).
+ * Use it to take the not-found check out of the handler, not as concealment.
+ */
+export interface MissingResourceOptions extends NotFoundResponseOptions {
+    /** What a missing resource answers. Default: `"check"`. */
+    readonly onMissingResource?: MissingResourceMode;
+}
+/** The decision recorded when `onMissingResource` refuses the request. */
+export declare const RESOURCE_NOT_FOUND_DECISION: PermissionDecision;
+/** The refusal for a missing resource, and the decision to record. */
+export interface MissingResourceRefusal {
+    readonly decision: PermissionDecision;
+    readonly response: PermissionHttpResponse;
+}
+/**
+ * Decide whether a loaded resource counts as missing, and answer for it.
+ *
+ * Only a guard that has an `extractResource` can have a missing resource: a
+ * route without one never loads anything, so it is always checked.
+ *
+ * @returns The refusal to send, or `undefined` to evaluate as usual.
+ */
+export declare function refuseMissingResource(extract: ResourceExtractor | undefined, resource: unknown, options: MissingResourceOptions & DeniedResponseOptions): MissingResourceRefusal | undefined;
 //# sourceMappingURL=httpResource.helper.d.ts.map

package/dist/http/httpResource.helper.js

@@ -3,6 +3,7 @@
  *
  * @module http/httpResource.helper
  */
+import { createForbiddenResponse, createNotFoundResponse, } from "./httpHelpers.js";
 /** The decision recorded when the resource loader fails. */
 export const RESOURCE_ERROR_DECISION = Object.freeze({
     allowed: false,
@@ -29,4 +30,30 @@ export async function loadResource(context, extract, onError) {
         return { ok: false, decision: RESOURCE_ERROR_DECISION };
     }
 }
+/** The decision recorded when `onMissingResource` refuses the request. */
+export const RESOURCE_NOT_FOUND_DECISION = Object.freeze({
+    allowed: false,
+    reason: "resource_not_found",
+    publicReason: "Access denied",
+});
+/**
+ * Decide whether a loaded resource counts as missing, and answer for it.
+ *
+ * Only a guard that has an `extractResource` can have a missing resource: a
+ * route without one never loads anything, so it is always checked.
+ *
+ * @returns The refusal to send, or `undefined` to evaluate as usual.
+ */
+export function refuseMissingResource(extract, resource, options) {
+    const mode = options.onMissingResource ?? "check";
+    if (!extract || mode === "check")
+        return undefined;
+    if (resource !== undefined && resource !== null)
+        return undefined;
+    const decision = RESOURCE_NOT_FOUND_DECISION;
+    const response = mode === "notFound"
+        ? createNotFoundResponse(options)
+        : createForbiddenResponse(decision, options);
+    return { decision, response };
+}
 //# sourceMappingURL=httpResource.helper.js.map

package/dist/http/index.d.ts

@@ -11,7 +11,7 @@
  * @module http
  */
 export { createActorMiddleware, createRequirePermissionMiddleware, authorize, createRequirePermissionsMiddleware, ACTOR_STATE_KEY, DECISION_STATE_KEY, DECISIONS_STATE_KEY, type AuthorizeMiddlewareOptions, type ActorMiddlewareOptions, type RequirePermissionMiddlewareOptions, type RequirePermissionsMiddlewareOptions, } from "./httpMiddleware.core.js";
-export { createForbiddenResponse, createUnauthorizedResponse, createJsonResponse, type DeniedResponseOptions, type PermissionHttpResponse, } from "./httpHelpers.js";
-export { loadResource, RESOURCE_ERROR_DECISION, type ResourceExtractor, type ResourceOutcome, } from "./httpResource.helper.js";
+export { createForbiddenResponse, createUnauthorizedResponse, createJsonResponse, createNotFoundResponse, type DeniedResponseOptions, type NotFoundResponseOptions, type PermissionHttpResponse, } from "./httpHelpers.js";
+export { loadResource, refuseMissingResource, RESOURCE_ERROR_DECISION, RESOURCE_NOT_FOUND_DECISION, type MissingResourceMode, type MissingResourceOptions, type MissingResourceRefusal, type ResourceExtractor, type ResourceOutcome, } from "./httpResource.helper.js";
 export type { HttpRequestBag, HttpMiddleware, HttpMiddlewareOutcome, HttpMiddlewareContext, HttpRequestContext, HttpResponseContext, HttpMiddlewareState, } from "./httpTypes.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/http/index.js

@@ -11,6 +11,6 @@
  * @module http
  */
 export { createActorMiddleware, createRequirePermissionMiddleware, authorize, createRequirePermissionsMiddleware, ACTOR_STATE_KEY, DECISION_STATE_KEY, DECISIONS_STATE_KEY, } from "./httpMiddleware.core.js";
-export { createForbiddenResponse, createUnauthorizedResponse, createJsonResponse, } from "./httpHelpers.js";
-export { loadResource, RESOURCE_ERROR_DECISION, } from "./httpResource.helper.js";
+export { createForbiddenResponse, createUnauthorizedResponse, createJsonResponse, createNotFoundResponse, } from "./httpHelpers.js";
+export { loadResource, refuseMissingResource, RESOURCE_ERROR_DECISION, RESOURCE_NOT_FOUND_DECISION, } from "./httpResource.helper.js";
 //# sourceMappingURL=index.js.map

package/dist/permissionTypes/policyTypes.d.ts

@@ -50,7 +50,13 @@ export interface PermissionCache {
  *   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.
+ *   Its deny (or a throw or timeout) *abstains*: the policy adds access but
+ *   never takes away what roles, permissions or rules grant. Use an explicit
+ *   deny rule or a constraining policy to deny.
+ *
+ * As an engine's `defaultPolicyEffect`, `"grant"` instead restores the
+ * pre-1.4 behaviour for policies that set no `effect`: an allow grants and a
+ * deny denies.
  */
 export type PolicyEffect = "constrain" | "grant";
 /** A named authorization policy. */
@@ -60,7 +66,7 @@ export interface PermissionPolicyDefinition {
      * 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.
+     * `"grant"` constrains. With `"grant"`, a deny abstains rather than denies.
      */
     readonly effect?: PolicyEffect;
     /**

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

@@ -18,4 +18,25 @@ export declare const DEFAULT_POLICY_EFFECT: PolicyEffect;
  * @param defaultEffect - The engine's `defaultPolicyEffect`.
  */
 export declare function policyGrants(policy: PermissionPolicyDefinition, defaultEffect?: PolicyEffect): boolean;
+/**
+ * How a policy's decision combines with RBAC/ABAC, once its own `effect`
+ * and the engine default are resolved.
+ *
+ * - `"constrain"`: an allow is "no objection", a deny denies.
+ * - `"grant"` (a policy's own `effect: "grant"`): an allow grants, a deny
+ *   *abstains* — the policy can add access but never take away what roles,
+ *   permissions or rules grant.
+ * - `"legacyGrant"` (a policy with no `effect` under an engine with
+ *   `defaultPolicyEffect: "grant"`): the pre-1.4 behaviour, kept for
+ *   backward compatibility — an allow grants and a deny denies.
+ */
+export type ResolvedPolicyMode = "constrain" | "grant" | "legacyGrant";
+/**
+ * Resolves a policy's {@link ResolvedPolicyMode}. Only the exact value
+ * `"grant"` grants; any other explicit value constrains.
+ *
+ * @param policy - The policy.
+ * @param defaultEffect - The engine's `defaultPolicyEffect`.
+ */
+export declare function resolvePolicyMode(policy: PermissionPolicyDefinition, defaultEffect?: PolicyEffect): ResolvedPolicyMode;
 //# sourceMappingURL=policyEffect.core.d.ts.map

package/dist/policy/policyEffect.core.js

@@ -19,4 +19,18 @@ export const DEFAULT_POLICY_EFFECT = "constrain";
 export function policyGrants(policy, defaultEffect = DEFAULT_POLICY_EFFECT) {
     return (policy.effect ?? defaultEffect) === "grant";
 }
+/**
+ * Resolves a policy's {@link ResolvedPolicyMode}. Only the exact value
+ * `"grant"` grants; any other explicit value constrains.
+ *
+ * @param policy - The policy.
+ * @param defaultEffect - The engine's `defaultPolicyEffect`.
+ */
+export function resolvePolicyMode(policy, defaultEffect = DEFAULT_POLICY_EFFECT) {
+    if (policy.effect === "grant")
+        return "grant";
+    if (policy.effect !== undefined)
+        return "constrain";
+    return defaultEffect === "grant" ? "legacyGrant" : "constrain";
+}
 //# sourceMappingURL=policyEffect.core.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/permissions",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Generic authorization engine with RBAC, ABAC, resource authorization, wildcards, role hierarchy, policies, and abilities.",
   "license": "MIT",
   "author": {