@zudojs/permissions 0.1.0 → 1.1.0

package/dist/evaluator/evaluator.pipeline.js

@@ -4,80 +4,225 @@
  * @module evaluator/evaluator.pipeline
  */
 import { resolveRolePermissions } from "../role/roleHierarchy.js";
-import { AuthorizationAbortedError } from "../permissionErrors/index.js";
+import { matches } from "../permission/permission.core.js";
+import { AuthorizationAbortedError, PermissionResolverError, PolicyError, PolicyTimeoutError, } from "../permissionErrors/index.js";
 /**
- * Resolve all permissions for an actor (direct + role-based).
+ * Normalize a thrown value into an `Error` before it reaches `onError`.
+ *
+ * A resolver or a policy is caller code and may throw anything at all — a
+ * string, `undefined`, a plain object. An `onError` handler that reads
+ * `error.message` then fails inside the failure path, so anything that is not
+ * already an `Error` is wrapped, keeping the original as `cause`.
  */
-export function resolveActorPermissions(actor, options) {
+function reportable(value, wrap) {
+    return value instanceof Error ? value : wrap(value);
+}
+/** Throws if the caller has cancelled the check. */
+export function assertNotAborted(signal) {
+    if (signal?.aborted)
+        throw new AuthorizationAbortedError();
+}
+/** Normalizes caller-supplied metadata into the map conditions read. */
+export function toMetadataMap(metadata) {
+    if (!metadata)
+        return undefined;
+    if (metadata instanceof Map)
+        return metadata;
+    return new Map(Object.entries(metadata));
+}
+/**
+ * Resolve everything an actor holds: direct permissions, role permissions
+ * (following inheritance), resolver-supplied roles and rules.
+ *
+ * A role the lookup cannot find is reported rather than thrown. An unknown
+ * role in a token is a data problem, and turning every request from that
+ * actor into an exception hands the decision to whichever error handler
+ * happens to be installed — which may well be more permissive than a denial.
+ */
+export async function resolveActorGrants(actor, options, signal) {
     const permissions = new Set();
-    // Direct permissions
-    if (actor.permissions) {
-        for (const p of actor.permissions)
-            permissions.add(p);
+    const rules = [...(options.rules ?? [])];
+    const unknownRoles = [];
+    for (const permission of actor.permissions ?? []) {
+        permissions.add(permission);
+    }
+    const roleNames = new Set(actor.roles ?? []);
+    if (options.roleResolver) {
+        assertNotAborted(signal);
+        try {
+            for (const role of await options.roleResolver.resolveRoles(actor)) {
+                roleNames.add(role);
+            }
+        }
+        catch (error) {
+            options.onError?.(reportable(error, (cause) => new PermissionResolverError("RoleResolver.resolveRoles failed", cause)), "RoleResolver.resolveRoles");
+        }
+    }
+    if (roleNames.size > 0 && options.getRole) {
+        try {
+            const resolution = resolveRolePermissions([...roleNames], options.getRole, { onUnknownRole: (name) => unknownRoles.push(name) });
+            for (const permission of resolution.permissions)
+                permissions.add(permission);
+            rules.push(...resolution.rules);
+        }
+        catch (error) {
+            // A cycle in the role graph, or a role source that throws, is a
+            // configuration failure. Throwing here would hand the outcome to
+            // whichever error handler the caller installed, which may well be more
+            // permissive than a denial — so every role is treated as unresolved and
+            // the check falls through to deny.
+            options.onError?.(error, "RoleHierarchy");
+            for (const name of roleNames) {
+                if (!unknownRoles.includes(name))
+                    unknownRoles.push(name);
+            }
+        }
     }
-    // Role-based permissions
+    if (options.permissionResolver) {
+        assertNotAborted(signal);
+        try {
+            rules.push(...(await options.permissionResolver.resolvePermissions(actor)));
+        }
+        catch (error) {
+            options.onError?.(reportable(error, (cause) => new PermissionResolverError("PermissionResolver.resolvePermissions failed", cause)), "PermissionResolver.resolvePermissions");
+        }
+    }
+    if (options.expandImplied) {
+        for (const permission of [...permissions]) {
+            for (const implied of options.expandImplied(permission)) {
+                permissions.add(implied);
+            }
+        }
+    }
+    return {
+        permissions: [...permissions],
+        rules,
+        unknownRoles,
+    };
+}
+/**
+ * Resolve all permission strings for an actor (direct + role-based).
+ *
+ * Kept for callers that only need the strings; the engine uses
+ * {@link resolveActorGrants}, which also carries rules and unknown roles.
+ */
+export function resolveActorPermissions(actor, options) {
+    const permissions = new Set(actor.permissions ?? []);
     if (actor.roles && options.getRole) {
-        const rolePerms = resolveRolePermissions(actor.roles, options.getRole);
-        for (const p of rolePerms)
-            permissions.add(p);
+        const resolution = resolveRolePermissions(actor.roles, options.getRole, {
+            onUnknownRole: () => { },
+        });
+        for (const permission of resolution.permissions)
+            permissions.add(permission);
     }
-    return Array.from(permissions);
+    return [...permissions];
+}
+/** Policies that apply to a permission, most important first. */
+export function selectPolicies(policies, permissionStr) {
+    return policies
+        .filter((policy) => 
+    // Wildcards work here for the same reason they work for grants: a
+    // policy registered for "post:*" is meant to cover "post:update".
+    policy.permissions.some((pattern) => matches(pattern, permissionStr)))
+        .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
 }
 /**
- * Evaluate policies for a context. Returns null if no policy matched.
+ * 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".
  */
-export async function evaluatePolicies(context, policies, authOptions) {
-    if (policies.length === 0)
-        return null;
+export async function evaluatePolicies(context, policies, options, authOptions) {
+    if (policies.length === 0) {
+        return { decision: null, cacheable: true, evaluated: [] };
+    }
     const permissionStr = `${context.permission.resource}:${context.permission.action}`;
-    const applicable = policies.filter((p) => p.permissions.includes(permissionStr));
-    if (applicable.length === 0)
-        return null;
+    const applicable = selectPolicies(policies, permissionStr);
+    if (applicable.length === 0) {
+        return { decision: null, cacheable: true, evaluated: [] };
+    }
+    // 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 = [];
+    let cacheable = true;
     for (const policy of applicable) {
+        assertNotAborted(context.signal ?? authOptions?.signal);
+        evaluated.push(policy.name);
+        if (policy.cacheable === false)
+            cacheable = false;
         try {
-            const result = await withTimeout(Promise.resolve(policy.evaluate(context)), authOptions?.policyTimeout);
+            const result = await withTimeout(Promise.resolve(policy.evaluate(context)), timeoutMs, policy.name);
             if (!result.allowed) {
-                return Object.freeze({
-                    allowed: false,
-                    reason: result.reason ?? `policy:${policy.name}`,
-                    policy: policy.name,
-                });
+                return {
+                    decision: Object.freeze({
+                        allowed: false,
+                        reason: result.reason ?? `policy:${policy.name}`,
+                        policy: policy.name,
+                        publicReason: result.publicReason ?? "Access denied",
+                    }),
+                    cacheable,
+                    evaluated,
+                };
             }
         }
         catch (error) {
             if (error instanceof AuthorizationAbortedError)
                 throw error;
-            // Policy error — fail closed
-            return Object.freeze({
-                allowed: false,
-                reason: `policy_error:${policy.name}`,
-                policy: policy.name,
-            });
+            options.onError?.(reportable(error, (cause) => new PolicyError(policy.name, cause)), `Policy.${policy.name}`);
+            // Policy error — fail closed.
+            return {
+                decision: Object.freeze({
+                    allowed: false,
+                    reason: `policy_error:${policy.name}`,
+                    policy: policy.name,
+                    publicReason: "Access denied",
+                }),
+                cacheable: false,
+                evaluated,
+            };
         }
     }
-    return Object.freeze({
-        allowed: true,
-        reason: "policy_allow",
-        policy: applicable.map((p) => p.name).join(","),
-    });
+    return {
+        decision: Object.freeze({
+            allowed: true,
+            reason: "policy_allow",
+            policy: applicable.map((policy) => policy.name).join(","),
+        }),
+        cacheable,
+        evaluated,
+    };
 }
 /**
  * Run a promise with an optional timeout.
+ *
+ * `0` means "expire immediately", not "no timeout" — treating a falsy value
+ * as "disabled" silently turned `policyTimeout: 0` into no timeout at all.
+ * Pass `undefined` to disable.
  */
-async function withTimeout(promise, timeoutMs) {
-    if (!timeoutMs)
+export async function withTimeout(promise, timeoutMs, policyName = "policy") {
+    if (timeoutMs === undefined)
         return promise;
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => {
-            reject(new Error("Policy timeout"));
-        }, timeoutMs);
-        promise.then((value) => {
-            clearTimeout(timer);
-            resolve(value);
-        }, (error) => {
+    let timer;
+    // Keep the loser handled so a late rejection cannot escape as an unhandled
+    // rejection once the race is over.
+    void promise.catch(() => { });
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => {
+                    reject(new PolicyTimeoutError(policyName, timeoutMs));
+                }, Math.max(0, timeoutMs));
+                if (typeof timer === "object" && "unref" in timer)
+                    timer.unref();
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
             clearTimeout(timer);
-            reject(error);
-        });
-    });
+    }
 }
 //# sourceMappingURL=evaluator.pipeline.js.map

package/dist/evaluator/index.d.ts

@@ -3,6 +3,8 @@
  *
  * @module evaluator
  */
-export { evaluate, evaluateWithExplain } from "./evaluator.core.js";
-export type { EvaluatorOptions } from "./evaluator.pipeline.js";
+export { evaluate, evaluateWithTrace } from "./evaluator.core.js";
+export { evaluateWithExplain } from "./evaluator.explain.js";
+export { resolveActorGrants, resolveActorPermissions, evaluatePolicies, selectPolicies, withTimeout, toMetadataMap, assertNotAborted, type EvaluatorOptions, type ResolvedGrants, type PolicyOutcome, } from "./evaluator.pipeline.js";
+export { createPermissionEngine, type PermissionEngine, type PermissionEngineOptions, } from "./authorizationEngine.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/evaluator/index.js

@@ -3,5 +3,8 @@
  *
  * @module evaluator
  */
-export { evaluate, evaluateWithExplain } from "./evaluator.core.js";
+export { evaluate, evaluateWithTrace } from "./evaluator.core.js";
+export { evaluateWithExplain } from "./evaluator.explain.js";
+export { resolveActorGrants, resolveActorPermissions, evaluatePolicies, selectPolicies, withTimeout, toMetadataMap, assertNotAborted, } from "./evaluator.pipeline.js";
+export { createPermissionEngine, } from "./authorizationEngine.js";
 //# sourceMappingURL=index.js.map

package/dist/http/httpHelpers.d.ts

@@ -6,23 +6,39 @@
 import type { PermissionDecision } from "../permissionTypes/index.js";
 /** Options for creating denied responses. */
 export interface DeniedResponseOptions {
-    /** Custom 403 response body function. */
+    /**
+     * Builds the 403 body. Receives the real decision, not a reconstruction of
+     * it, so `policy`, `matchedPermission` and `metadata` are all available.
+     */
     readonly deniedResponse?: (decision: PermissionDecision) => unknown;
+    /** Builds the 401 body for an unauthenticated request. */
+    readonly unauthenticatedResponse?: () => unknown;
+    /** 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>>;
 }
 /**
- * Create a 403 Forbidden JSON response.
+ * Create a 403 Forbidden JSON response for a decision.
+ *
+ * The default body carries `decision.publicReason`, never `decision.reason`:
+ * the internal reason names policies and rules (`policy_error:billingOwner`),
+ * which tells a prober about the authorization model.
  */
-export declare function createForbiddenResponse(reason: string, options?: DeniedResponseOptions): {
-    readonly status: 403;
-    readonly body: unknown;
-    readonly headers: Record<string, string>;
-};
+export declare function createForbiddenResponse(decision: PermissionDecision, options?: DeniedResponseOptions): PermissionHttpResponse;
+/**
+ * Create a 401 Unauthorized JSON response.
+ *
+ * A missing actor is not the same as a denied one: answering both with 403
+ * leaves a client unable to tell "log in" from "you may not do this".
+ */
+export declare function createUnauthorizedResponse(options?: DeniedResponseOptions): PermissionHttpResponse;
 /**
  * Create a JSON response.
  */
-export declare function createJsonResponse(status: number, body: unknown): {
-    readonly status: number;
-    readonly body: unknown;
-    readonly headers: Record<string, string>;
-};
+export declare function createJsonResponse(status: number, body: unknown): PermissionHttpResponse;
 //# sourceMappingURL=httpHelpers.d.ts.map

package/dist/http/httpHelpers.js

@@ -3,17 +3,44 @@
  *
  * @module http/httpHelpers
  */
+const JSON_HEADERS = { "content-type": "application/json" };
 /**
- * Create a 403 Forbidden JSON response.
+ * Create a 403 Forbidden JSON response for a decision.
+ *
+ * The default body carries `decision.publicReason`, never `decision.reason`:
+ * the internal reason names policies and rules (`policy_error:billingOwner`),
+ * which tells a prober about the authorization model.
  */
-export function createForbiddenResponse(reason, options) {
+export function createForbiddenResponse(decision, options) {
     const body = options?.deniedResponse
-        ? options.deniedResponse({ allowed: false, reason })
-        : { error: "Forbidden", message: reason };
+        ? options.deniedResponse(decision)
+        : {
+            error: "Forbidden",
+            message: decision.publicReason ?? "Access denied",
+        };
     return Object.freeze({
         status: 403,
         body,
-        headers: { "content-type": "application/json" },
+        headers: JSON_HEADERS,
+    });
+}
+/**
+ * Create a 401 Unauthorized JSON response.
+ *
+ * A missing actor is not the same as a denied one: answering both with 403
+ * leaves a client unable to tell "log in" from "you may not do this".
+ */
+export function createUnauthorizedResponse(options) {
+    const body = options?.unauthenticatedResponse
+        ? options.unauthenticatedResponse()
+        : { error: "Unauthorized", message: "Authentication required" };
+    return Object.freeze({
+        status: 401,
+        body,
+        headers: Object.freeze({
+            ...JSON_HEADERS,
+            "www-authenticate": options?.authenticateChallenge ?? "Bearer",
+        }),
     });
 }
 /**
@@ -23,7 +50,7 @@ export function createJsonResponse(status, body) {
     return Object.freeze({
         status,
         body,
-        headers: { "content-type": "application/json" },
+        headers: JSON_HEADERS,
     });
 }
 //# sourceMappingURL=httpHelpers.js.map

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

@@ -6,43 +6,84 @@
  *
  * @module http/httpMiddleware
  */
-import type { PermissionActor, PermissionDecision, AuthorizationOptions } from "../permissionTypes/index.js";
+import type { PermissionActor, AuthorizationOptions } from "../permissionTypes/index.js";
 import type { PermissionEngine } from "../evaluator/authorizationEngine.js";
 import type { HttpMiddleware, HttpMiddlewareContext } from "./httpTypes.js";
-/** Options for the authorize middleware. */
-export interface AuthorizeMiddlewareOptions {
-    /** Function to extract an actor from the request context. */
-    readonly extractActor: (context: HttpMiddlewareContext) => PermissionActor | Promise<PermissionActor> | undefined;
-    /** Authorization options (signal, policyTimeout). */
+import { type DeniedResponseOptions } from "./httpHelpers.js";
+/** Options shared by the permission middleware. */
+export interface AuthorizeMiddlewareOptions extends DeniedResponseOptions {
+    /**
+     * Extracts an actor from the request context.
+     *
+     * The guard middleware calls this itself when no actor is already in
+     * state, so `authorize(engine, permission, { extractActor })` works on its
+     * own — installing `createActorMiddleware` first is an optimisation, not a
+     * requirement.
+     */
+    readonly extractActor?: (context: HttpMiddlewareContext) => PermissionActor | Promise<PermissionActor> | undefined;
+    /** Authorization options (policyTimeout, metadata). */
     readonly authorization?: AuthorizationOptions;
-    /** Custom 403 response body. */
-    readonly deniedResponse?: (decision: PermissionDecision) => unknown;
+    /**
+     * Forwards `context.signal` to the engine so a client disconnect stops
+     * policy evaluation. Default: `true`.
+     */
+    readonly forwardSignal?: boolean;
+    /** Builds per-request metadata for conditions and policies. */
+    readonly extractMetadata?: (context: HttpMiddlewareContext) => Record<string, unknown> | undefined;
 }
 /** Options for the requirePermission middleware. */
 export interface RequirePermissionMiddlewareOptions extends AuthorizeMiddlewareOptions {
     /** The permission to check (e.g. "post:update"). */
     readonly permission: string;
-    /** Function to extract the resource from the request (optional). */
+    /** Extracts the resource from the request (optional). */
     readonly extractResource?: (context: HttpMiddlewareContext) => unknown;
 }
+/** Options for {@link createActorMiddleware}. */
+export interface ActorMiddlewareOptions extends AuthorizeMiddlewareOptions {
+    /** Required: this middleware exists to run it. */
+    readonly extractActor: (context: HttpMiddlewareContext) => PermissionActor | Promise<PermissionActor> | undefined;
+    /**
+     * Answer 401 immediately when no actor could be extracted, instead of
+     * letting the request continue to whatever comes next. Default: `false`,
+     * preserving the "authenticate here, authorize later" split.
+     */
+    readonly requireActor?: boolean;
+}
 /** State key for the current actor. */
 export declare const ACTOR_STATE_KEY = "permissions:actor";
 /** State key for the authorization decision. */
 export declare const DECISION_STATE_KEY = "permissions:decision";
+/** State key for the batch decision map. */
+export declare const DECISIONS_STATE_KEY = "permissions:decisions";
 /**
  * Create middleware that extracts the actor from the request and stores it in state.
  */
-export declare function createActorMiddleware(options: AuthorizeMiddlewareOptions): HttpMiddleware;
+export declare function createActorMiddleware(options: ActorMiddlewareOptions): HttpMiddleware;
 /**
  * Create middleware that checks a permission and returns 403 if denied.
+ *
+ * An unauthenticated request gets 401; an authenticated one that is not
+ * permitted gets 403.
  */
 export declare function createRequirePermissionMiddleware(engine: PermissionEngine, options: RequirePermissionMiddlewareOptions): HttpMiddleware;
 /**
  * Create middleware that checks a permission and short-circuits on denial.
  */
-export declare function authorize(engine: PermissionEngine, permission: string, options: Omit<RequirePermissionMiddlewareOptions, "permission">): HttpMiddleware;
+export declare function authorize(engine: PermissionEngine, permission: string, options?: Omit<RequirePermissionMiddlewareOptions, "permission">): HttpMiddleware;
+/** Options for {@link createRequirePermissionsMiddleware}. */
+export interface RequirePermissionsMiddlewareOptions extends AuthorizeMiddlewareOptions {
+    /** Extracts the resource checked for every permission (optional). */
+    readonly extractResource?: (context: HttpMiddlewareContext) => unknown;
+    /**
+     * `"all"` (default) requires every permission; `"any"` requires one.
+     */
+    readonly mode?: "all" | "any";
+}
 /**
- * Create middleware that checks multiple permissions in batch.
+ * Create middleware that checks multiple permissions.
+ *
+ * Under `"all"` the first denial short-circuits: evaluating the rest costs
+ * policy calls and timeouts for an answer that is already decided.
  */
-export declare function createRequirePermissionsMiddleware(engine: PermissionEngine, permissions: readonly string[], options: AuthorizeMiddlewareOptions): HttpMiddleware;
+export declare function createRequirePermissionsMiddleware(engine: PermissionEngine, permissions: readonly string[], options?: RequirePermissionsMiddlewareOptions): HttpMiddleware;
 //# sourceMappingURL=httpMiddleware.core.d.ts.map

package/dist/http/httpMiddleware.core.js

@@ -6,12 +6,37 @@
  *
  * @module http/httpMiddleware
  */
-import { createForbiddenResponse, createJsonResponse } from "./httpHelpers.js";
+import { createForbiddenResponse, createUnauthorizedResponse, } from "./httpHelpers.js";
 // ─── State Keys ───────────────────────────────────────────────────────────
 /** State key for the current actor. */
 export const ACTOR_STATE_KEY = "permissions:actor";
 /** State key for the authorization decision. */
 export const DECISION_STATE_KEY = "permissions:decision";
+/** State key for the batch decision map. */
+export const DECISIONS_STATE_KEY = "permissions:decisions";
+// ─── Helpers ──────────────────────────────────────────────────────────────
+/**
+ * Finds the actor for a request: from state first, then by extracting it.
+ */
+async function resolveActor(context, options) {
+    const existing = context.state.get(ACTOR_STATE_KEY);
+    if (existing)
+        return existing;
+    if (!options.extractActor)
+        return undefined;
+    const actor = await options.extractActor(context);
+    if (actor)
+        context.state.set(ACTOR_STATE_KEY, actor);
+    return actor;
+}
+function buildAuthorization(context, options) {
+    const metadata = options.extractMetadata?.(context);
+    return {
+        ...options.authorization,
+        ...(options.forwardSignal !== false ? { signal: context.signal } : {}),
+        ...(metadata ? { metadata } : {}),
+    };
+}
 // ─── Middleware Factories ──────────────────────────────────────────────────
 /**
  * Create middleware that extracts the actor from the request and stores it in state.
@@ -22,59 +47,78 @@ export function createActorMiddleware(options) {
         if (actor) {
             context.state.set(ACTOR_STATE_KEY, actor);
         }
+        else if (options.requireActor === true) {
+            return createUnauthorizedResponse(options);
+        }
         return next();
     };
 }
 /**
  * Create middleware that checks a permission and returns 403 if denied.
+ *
+ * An unauthenticated request gets 401; an authenticated one that is not
+ * permitted gets 403.
  */
 export function createRequirePermissionMiddleware(engine, options) {
     return async (context, next) => {
-        const actor = context.state.get(ACTOR_STATE_KEY);
-        if (!actor) {
-            return createForbiddenResponse("No actor found in request context", options);
-        }
+        const actor = await resolveActor(context, options);
+        if (!actor)
+            return createUnauthorizedResponse(options);
         const resource = options.extractResource?.(context);
-        const decision = await engine.check(actor, options.permission, resource, options.authorization);
+        const decision = await engine.check(actor, options.permission, resource, buildAuthorization(context, options));
         context.state.set(DECISION_STATE_KEY, decision);
-        if (!decision.allowed) {
-            return createForbiddenResponse(decision.reason ?? "Access denied", options);
-        }
+        if (!decision.allowed)
+            return createForbiddenResponse(decision, options);
         return next();
     };
 }
 /**
  * Create middleware that checks a permission and short-circuits on denial.
  */
-export function authorize(engine, permission, options) {
+export function authorize(engine, permission, options = {}) {
     return createRequirePermissionMiddleware(engine, {
+        ...options,
         permission,
-        extractActor: options.extractActor,
-        authorization: options.authorization,
-        deniedResponse: options.deniedResponse,
-        extractResource: options.extractResource,
     });
 }
 /**
- * Create middleware that checks multiple permissions in batch.
+ * Create middleware that checks multiple permissions.
+ *
+ * Under `"all"` the first denial short-circuits: evaluating the rest costs
+ * policy calls and timeouts for an answer that is already decided.
  */
-export function createRequirePermissionsMiddleware(engine, permissions, options) {
+export function createRequirePermissionsMiddleware(engine, permissions, options = {}) {
+    const mode = options.mode ?? "all";
     return async (context, next) => {
-        const actor = context.state.get(ACTOR_STATE_KEY);
-        if (!actor) {
-            return createForbiddenResponse("No actor found in request context", options);
-        }
+        const actor = await resolveActor(context, options);
+        if (!actor)
+            return createUnauthorizedResponse(options);
+        const resource = options.extractResource?.(context);
+        const authorization = buildAuthorization(context, options);
         const results = new Map();
-        for (const perm of permissions) {
-            const decision = await engine.check(actor, perm, undefined, options.authorization);
-            results.set(perm, decision);
-        }
-        context.state.set("permissions:decisions", results);
-        for (const [perm, decision] of results) {
-            if (!decision.allowed) {
-                return createForbiddenResponse(decision.reason ?? `Missing permission: ${perm}`, options);
+        let lastDenial;
+        for (const permission of permissions) {
+            const decision = await engine.check(actor, permission, resource, authorization);
+            results.set(permission, decision);
+            if (decision.allowed) {
+                if (mode === "any") {
+                    context.state.set(DECISIONS_STATE_KEY, results);
+                    return next();
+                }
+            }
+            else {
+                lastDenial = decision;
+                if (mode === "all")
+                    break;
             }
         }
+        context.state.set(DECISIONS_STATE_KEY, results);
+        if (mode === "all" && lastDenial) {
+            return createForbiddenResponse(lastDenial, options);
+        }
+        if (mode === "any") {
+            return createForbiddenResponse(lastDenial ?? { allowed: false, publicReason: "Access denied" }, options);
+        }
         return next();
     };
 }