@zudojs/permissions 1.3.0 → 1.4.1

package/README.md

@@ -153,33 +153,111 @@ 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,
+      }),
+    },
+  ],
+});
+
+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, 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.
@@ -428,7 +506,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
@@ -442,9 +524,60 @@ 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).
+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";
 /**
@@ -57,6 +57,18 @@ 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 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"`. */
     readonly algorithm?: RuleCombiningAlgorithm;
     /** Caches decisions. Create one with `createMemoryPermissionCache()`. */

package/dist/evaluator/authorizationEngine.js

@@ -144,6 +144,7 @@ export function createPermissionEngine(options) {
         },
         rules: options?.rules,
         policyTimeout: options?.policyTimeout,
+        defaultPolicyEffect: options?.defaultPolicyEffect,
         algorithm: options?.algorithm,
         cache: options?.cache,
         cacheTtlMs: options?.cacheTtlMs,

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,20 @@ 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. 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
+ * — 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 +237,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. */
@@ -80,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: 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;
 }
 /**
  * Evaluate policies for a context.
@@ -87,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,6 +3,7 @@
  *
  * @module evaluator/evaluator.pipeline
  */
+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";
@@ -144,76 +145,97 @@ 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) {
-        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.
     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) {
-        return { decision: null, cacheable, evaluated };
+    if (allowedBy.length === 0) {
+        return { decision: null, cacheable, evaluated, grants: false };
     }
     return {
         decision: Object.freeze({
             allowed: true,
-            reason: "policy_allow",
-            policy: applicable.map((policy) => policy.name).join(","),
+            reason: grants ? "policy_allow" : "policy_pass",
+            policy: allowedBy.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.
  *
@@ -37,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

@@ -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,29 @@ 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 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.
  */
 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/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/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

@@ -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 type { HttpRequestBag, HttpMiddleware, HttpMiddlewareContext, HttpRequestContext, HttpResponseContext, HttpMiddlewareState, } from "./httpTypes.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/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,33 @@ 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.
+ *   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. */
 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. With `"grant"`, a deny abstains rather than denies.
+     */
+    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,42 @@
+/**
+ * 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;
+/**
+ * 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

@@ -0,0 +1,36 @@
+/**
+ * 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";
+}
+/**
+ * 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.3.0",
+  "version": "1.4.1",
   "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.2.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"
   },