@zudojs/permissions 1.1.0 → 1.2.0

package/dist/evaluator/engineSupport/authorizationEngine.validation.js

@@ -0,0 +1,90 @@
+/**
+ * Configuration validation for the authorization engine.
+ *
+ * A malformed pattern can never match. In a grant that is a silent no-op; in
+ * a denying policy or a deny rule it is a restriction that fails open. The
+ * same pattern therefore has to be rejected wherever it can be written, not
+ * only in a role's grant list.
+ *
+ * @module evaluator/authorizationEngine.validation
+ */
+import { InvalidPermissionError, InvalidRoleError, } from "../../permissionErrors/index.js";
+import { isValidPermission } from "../../permission/permission.core.js";
+function patterns(value) {
+    return Array.isArray(value) ? value : [value];
+}
+/**
+ * The first `resource:action` pair a rule names that is not a valid
+ * permission pattern, or `undefined` when every pair is valid.
+ */
+export function invalidRulePattern(rule) {
+    const resources = patterns(rule.resource);
+    const actions = patterns(rule.action);
+    if (resources.length === 0 || actions.length === 0) {
+        return `${resources.join(",")}:${actions.join(",")}`;
+    }
+    for (const resource of resources) {
+        for (const action of actions) {
+            const pair = `${String(resource)}:${String(action)}`;
+            if (!isValidPermission(pair))
+                return pair;
+        }
+    }
+    return undefined;
+}
+/**
+ * Reject a rule whose resource or action could never match.
+ *
+ * @throws {InvalidPermissionError} naming the offending pair.
+ */
+export function validateRule(rule) {
+    const invalid = invalidRulePattern(rule);
+    if (invalid !== undefined)
+        throw new InvalidPermissionError(invalid);
+}
+/**
+ * Reject a policy scoped to a pattern that could never match.
+ *
+ * @throws {InvalidPermissionError} naming the offending pattern.
+ */
+export function validatePolicy(policy) {
+    for (const pattern of policy.permissions) {
+        if (!isValidPermission(pattern))
+            throw new InvalidPermissionError(pattern);
+    }
+}
+/**
+ * Reject a role whose grants or rules could never match.
+ *
+ * @throws {InvalidRoleError} naming the role and the offending pattern.
+ */
+export function validateRole(role) {
+    if (!role.name || role.name.trim() === "") {
+        throw new InvalidRoleError("Role name cannot be empty");
+    }
+    for (const permission of role.permissions) {
+        if (!isValidPermission(permission)) {
+            throw new InvalidRoleError(`Role "${role.name}" grants "${permission}", which is not a valid ` +
+                `"resource:action" permission`);
+        }
+    }
+    for (const rule of role.rules ?? []) {
+        const invalid = invalidRulePattern(rule);
+        if (invalid !== undefined) {
+            throw new InvalidRoleError(`Role "${role.name}" has a rule on "${invalid}", which is not a valid ` +
+                `"resource:action" pattern`);
+        }
+    }
+}
+/** Validate a role list, rejecting duplicates as well. */
+export function validateRoles(roles) {
+    const seen = new Set();
+    for (const role of roles) {
+        validateRole(role);
+        if (seen.has(role.name)) {
+            throw new InvalidRoleError(`Role "${role.name}" is defined more than once`);
+        }
+        seen.add(role.name);
+    }
+}
+//# sourceMappingURL=authorizationEngine.validation.js.map

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

@@ -0,0 +1,24 @@
+/**
+ * Decision cache key for one evaluation.
+ *
+ * @module evaluator/evaluator.cacheKey
+ */
+import type { AuthorizationOptions, PermissionActor } from "../../permissionTypes/index.js";
+import type { EvaluatorOptions } from "../evaluator.pipeline.js";
+/**
+ * The cache key for a decision, or `undefined` when it must not be cached.
+ *
+ * Only a decision the key can describe completely may be cached:
+ *
+ * - A resource with no derivable id would collapse the key to
+ *   `actor|permission`, so an allow for `{ ownerId: "ada" }` would answer for
+ *   `{ ownerId: "bob" }`.
+ * - Request metadata is not in the key, and `tenantIsolation()` reads the
+ *   tenant from it.
+ * - The actor's roles, permissions, type and any other field it carries are
+ *   in the key as a digest; an actor the digest cannot describe is not cached.
+ * - The engine's configuration generation is in the key, so a role removed
+ *   from a live registry cannot be served from an entry written before.
+ */
+export declare function decisionCacheKey(actor: PermissionActor, permissionStr: string, resource: unknown, options: EvaluatorOptions, authOptions?: AuthorizationOptions): string | undefined;
+//# sourceMappingURL=evaluator.cacheKey.d.ts.map

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

@@ -0,0 +1,56 @@
+/**
+ * Decision cache key for one evaluation.
+ *
+ * @module evaluator/evaluator.cacheKey
+ */
+import { permissionCacheKey } from "../../cache/cache.core.js";
+import { actorCacheDigest } from "../../cache/cache.actorDigest.js";
+/** True when the caller supplied request metadata the cache key cannot carry. */
+function hasMetadata(metadata) {
+    if (!metadata)
+        return false;
+    if (metadata instanceof Map)
+        return metadata.size > 0;
+    return Object.keys(metadata).length > 0;
+}
+/** Best-effort resource identity for the cache key. */
+function resourceIdOf(resource) {
+    if (typeof resource !== "object" || resource === null)
+        return undefined;
+    const id = resource.id;
+    if (typeof id === "string")
+        return id;
+    if (typeof id === "number")
+        return String(id);
+    return undefined;
+}
+/**
+ * The cache key for a decision, or `undefined` when it must not be cached.
+ *
+ * Only a decision the key can describe completely may be cached:
+ *
+ * - A resource with no derivable id would collapse the key to
+ *   `actor|permission`, so an allow for `{ ownerId: "ada" }` would answer for
+ *   `{ ownerId: "bob" }`.
+ * - Request metadata is not in the key, and `tenantIsolation()` reads the
+ *   tenant from it.
+ * - The actor's roles, permissions, type and any other field it carries are
+ *   in the key as a digest; an actor the digest cannot describe is not cached.
+ * - The engine's configuration generation is in the key, so a role removed
+ *   from a live registry cannot be served from an entry written before.
+ */
+export function decisionCacheKey(actor, permissionStr, resource, options, authOptions) {
+    if (!options.cache || authOptions?.skipCache === true)
+        return undefined;
+    const resourceId = authOptions?.resourceId ?? resourceIdOf(resource);
+    if (resource !== undefined && resourceId === undefined)
+        return undefined;
+    if (hasMetadata(authOptions?.metadata))
+        return undefined;
+    const digest = actorCacheDigest(actor);
+    if (digest === undefined)
+        return undefined;
+    const generation = options.cacheScope?.() ?? "";
+    return permissionCacheKey(actor.id, permissionStr, resourceId, `${generation}${digest}`);
+}
+//# sourceMappingURL=evaluator.cacheKey.js.map

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

@@ -0,0 +1,18 @@
+/**
+ * Audit-event wrapper shared by every path that makes a decision.
+ *
+ * @module evaluator/evaluator.observed
+ */
+import type { PermissionActor, PermissionDecision } from "../../permissionTypes/index.js";
+import type { PermissionEventEmitter } from "../../observability/observability.core.js";
+/** Best-effort resource type for an audit event. */
+export declare function resourceTypeOf(resource: unknown): string | undefined;
+/**
+ * Run one authorization and emit an audit event whichever way it ends —
+ * including when it throws. An authorization trail that records only the
+ * successful paths is not a trail, and one that skips `explain()` misses
+ * decisions that are real: they run the same evaluation and write the same
+ * cache entries that later checks are served from.
+ */
+export declare function observed<T>(emitter: PermissionEventEmitter | undefined, actor: PermissionActor, permission: string, resource: unknown, run: () => Promise<T>, decisionOf: (result: T) => PermissionDecision): Promise<T>;
+//# sourceMappingURL=evaluator.observed.d.ts.map

package/dist/evaluator/engineSupport/evaluator.observed.js

@@ -0,0 +1,49 @@
+/**
+ * Audit-event wrapper shared by every path that makes a decision.
+ *
+ * @module evaluator/evaluator.observed
+ */
+/** Best-effort resource type for an audit event. */
+export function resourceTypeOf(resource) {
+    if (typeof resource !== "object" || resource === null)
+        return undefined;
+    const record = resource;
+    if (typeof record.type === "string")
+        return record.type;
+    const name = record.constructor?.name;
+    return name && name !== "Object" ? name : undefined;
+}
+/**
+ * Run one authorization and emit an audit event whichever way it ends —
+ * including when it throws. An authorization trail that records only the
+ * successful paths is not a trail, and one that skips `explain()` misses
+ * decisions that are real: they run the same evaluation and write the same
+ * cache entries that later checks are served from.
+ */
+export async function observed(emitter, actor, permission, resource, run, decisionOf) {
+    const start = performance.now();
+    let decision;
+    let failure;
+    try {
+        const result = await run();
+        decision = decisionOf(result);
+        return result;
+    }
+    catch (error) {
+        failure = error;
+        throw error;
+    }
+    finally {
+        emitter?.emit({
+            actorId: actor.id,
+            permission,
+            resourceType: resourceTypeOf(resource),
+            allowed: decision?.allowed ?? false,
+            reason: decision?.reason ??
+                (failure instanceof Error ? `error:${failure.name}` : undefined),
+            durationMs: performance.now() - start,
+            errored: failure !== undefined,
+        });
+    }
+}
+//# sourceMappingURL=evaluator.observed.js.map

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

@@ -0,0 +1,10 @@
+/**
+ * Support for the authorization engine: configuration validation, the
+ * decision-cache key, and the audit-event wrapper every decision path uses.
+ *
+ * @module evaluator/engineSupport
+ */
+export { invalidRulePattern, validatePolicy, validateRole, validateRoles, validateRule, } from "./authorizationEngine.validation.js";
+export { decisionCacheKey } from "./evaluator.cacheKey.js";
+export { observed, resourceTypeOf } from "./evaluator.observed.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/evaluator/engineSupport/index.js

@@ -0,0 +1,10 @@
+/**
+ * Support for the authorization engine: configuration validation, the
+ * decision-cache key, and the audit-event wrapper every decision path uses.
+ *
+ * @module evaluator/engineSupport
+ */
+export { invalidRulePattern, validatePolicy, validateRole, validateRoles, validateRule, } from "./authorizationEngine.validation.js";
+export { decisionCacheKey } from "./evaluator.cacheKey.js";
+export { observed, resourceTypeOf } from "./evaluator.observed.js";
+//# sourceMappingURL=index.js.map

package/dist/evaluator/evaluator.core.js

@@ -8,12 +8,13 @@
  *
  * @module evaluator/evaluator
  */
-import { parsePermissionSafe, matches } from "../permission/permission.core.js";
+import { parsePermissionSafe, matches, permissionsOverlap, } from "../permission/permission.core.js";
 import { InvalidPermissionError } from "../permissionErrors/index.js";
 import { compileRules, findMatchingRules } from "../rule/ruleCompiler.js";
 import { evaluateRules } from "../rule/rule.core.js";
+import { isWildcardTarget } from "../rule/rule.pattern.js";
 import { assertNotAborted, evaluatePolicies, resolveActorGrants, toMetadataMap, } from "./evaluator.pipeline.js";
-import { permissionCacheKey } from "../cache/cache.core.js";
+import { decisionCacheKey } from "./engineSupport/index.js";
 export { evaluateWithExplain } from "./evaluator.explain.js";
 /** A public message that names nothing internal. */
 const PUBLIC_DENIED = "Access denied";
@@ -66,7 +67,10 @@ export async function evaluate(actor, permissionStr, resource, options, authOpti
             });
             continue;
         }
-        if (matches(deny, permissionStr)) {
+        // Overlap, not match: for a concrete target the two are the same, but a
+        // wildcard target (`post:*`) asks about every action under it, and a
+        // deny on one of them has to refuse it.
+        if (permissionsOverlap(deny, permissionStr)) {
             trace?.push({
                 type: "deny",
                 detail: `Explicit deny: ${deny}`,
@@ -76,19 +80,7 @@ export async function evaluate(actor, permissionStr, resource, options, authOpti
         }
     }
     /* ── Cache ───────────────────────────────────────────────────────────── */
-    const resourceId = authOptions?.resourceId ?? resourceIdOf(resource);
-    // Only a decision the key can fully describe may be cached.
-    //
-    // A resource with no derivable id is the sharp case: the key would collapse
-    // to `actor|permission`, so an allow for `{ ownerId: "ada" }` would answer
-    // for `{ ownerId: "bob" }` on the next call. Request metadata is the other:
-    // `tenantIsolation()` reads the tenant from it, and it is not part of the
-    // key, so a decision made for one tenant must not answer for another.
-    const keyable = (resource === undefined || resourceId !== undefined) &&
-        !hasMetadata(authOptions?.metadata);
-    const cacheKey = options.cache && authOptions?.skipCache !== true && keyable
-        ? permissionCacheKey(actor.id, permissionStr, resourceId)
-        : undefined;
+    const cacheKey = decisionCacheKey(actor, permissionStr, resource, options, authOptions);
     if (options.cache && cacheKey) {
         try {
             const cached = await options.cache.get(cacheKey);
@@ -160,9 +152,16 @@ export async function evaluate(actor, permissionStr, resource, options, authOpti
         })),
         ...grants.rules,
     ];
-    const ruleResult = await evaluateRules(findMatchingRules(compileRules(rules), permission), permission, context, {
+    // A wildcard target is not a key the index can look up, and the deny
+    // rules that merely overlap it are exactly the ones an index lookup misses,
+    // so it is checked against every rule.
+    let conditionFailed = false;
+    const ruleResult = await evaluateRules(isWildcardTarget(permission)
+        ? rules
+        : findMatchingRules(compileRules(rules), permission), permission, context, {
         algorithm: options.algorithm,
         onConditionError: (rule, error) => {
+            conditionFailed = true;
             options.onError?.(error, `RuleCondition.${rule.name ?? "unnamed"}`);
         },
     });
@@ -188,7 +187,9 @@ export async function evaluate(actor, permissionStr, resource, options, authOpti
     }
     const decision = combine(ruleResult, outcome.decision, permissionStr);
     /* ── Cache write ─────────────────────────────────────────────────────── */
-    if (options.cache && cacheKey && outcome.cacheable) {
+    // A decision forced by a condition that threw describes the failure, not
+    // the actor, and must not outlive it.
+    if (options.cache && cacheKey && outcome.cacheable && !conditionFailed) {
         try {
             await options.cache.set(cacheKey, decision, {
                 ttl: options.cacheTtlMs,
@@ -235,25 +236,6 @@ function combine(ruleResult, policyDecision, permissionStr) {
         return policyDecision;
     return denied("no_matching_rule");
 }
-/** True when the caller supplied request metadata the cache key cannot carry. */
-function hasMetadata(metadata) {
-    if (!metadata)
-        return false;
-    if (metadata instanceof Map)
-        return metadata.size > 0;
-    return Object.keys(metadata).length > 0;
-}
-/** Best-effort resource identity for the cache key. */
-function resourceIdOf(resource) {
-    if (typeof resource !== "object" || resource === null)
-        return undefined;
-    const id = resource.id;
-    if (typeof id === "string")
-        return id;
-    if (typeof id === "number")
-        return String(id);
-    return undefined;
-}
 /**
  * Evaluate and collect the trace, in one pass.
  *

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

@@ -31,6 +31,12 @@ export interface EvaluatorOptions {
     readonly expandImplied?: (permission: string) => readonly string[];
     /** Reports a failure that authorization swallowed to stay fail-closed. */
     readonly onError?: (error: unknown, source: string) => void;
+    /**
+     * Extra decision-cache key scope, read on every evaluation. The engine
+     * passes its configuration generation, so a role change invalidates every
+     * entry written before it.
+     */
+    readonly cacheScope?: () => string;
 }
 /** The permissions and rules an actor holds, once everything is resolved. */
 export interface ResolvedGrants {

package/dist/evaluator/evaluator.pipeline.js

@@ -4,7 +4,8 @@
  * @module evaluator/evaluator.pipeline
  */
 import { resolveRolePermissions } from "../role/roleHierarchy.js";
-import { matches } from "../permission/permission.core.js";
+import { matches, permissionsOverlap, parsePermissionSafe, } from "../permission/permission.core.js";
+import { isWildcardTarget } from "../rule/rule.pattern.js";
 import { AuthorizationAbortedError, PermissionResolverError, PolicyError, PolicyTimeoutError, } from "../permissionErrors/index.js";
 /**
  * Normalize a thrown value into an `Error` before it reaches `onError`.
@@ -126,6 +127,23 @@ export function selectPolicies(policies, permissionStr) {
     policy.permissions.some((pattern) => matches(pattern, permissionStr)))
         .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
 }
+/**
+ * Policies narrower than a wildcard target, which may deny it but not grant it.
+ *
+ * `can(actor, "post:*")` asks about every action under `post`. A policy
+ * registered for `post:delete` does not cover that question, so its allow
+ * must not grant it — but its denial is a denial of part of it, and a
+ * wildcard check must not side-step it.
+ */
+function narrowerPolicies(policies, applicable, permissionStr) {
+    const target = parsePermissionSafe(permissionStr);
+    if (!target || !isWildcardTarget(target))
+        return [];
+    return policies
+        .filter((policy) => !applicable.includes(policy) &&
+        policy.permissions.some((pattern) => permissionsOverlap(pattern, permissionStr)))
+        .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+}
 /**
  * Evaluate policies for a context.
  *
@@ -139,7 +157,8 @@ export async function evaluatePolicies(context, policies, options, authOptions)
     }
     const permissionStr = `${context.permission.resource}:${context.permission.action}`;
     const applicable = selectPolicies(policies, permissionStr);
-    if (applicable.length === 0) {
+    const denyOnly = narrowerPolicies(policies, applicable, permissionStr);
+    if (applicable.length === 0 && denyOnly.length === 0) {
         return { decision: null, cacheable: true, evaluated: [] };
     }
     // The per-call timeout wins, but the engine-level default is what makes a
@@ -147,7 +166,7 @@ export async function evaluatePolicies(context, policies, options, authOptions)
     const timeoutMs = authOptions?.policyTimeout ?? options.policyTimeout;
     const evaluated = [];
     let cacheable = true;
-    for (const policy of applicable) {
+    for (const policy of [...applicable, ...denyOnly]) {
         assertNotAborted(context.signal ?? authOptions?.signal);
         evaluated.push(policy.name);
         if (policy.cacheable === false)
@@ -184,6 +203,9 @@ export async function evaluatePolicies(context, policies, options, authOptions)
             };
         }
     }
+    if (applicable.length === 0) {
+        return { decision: null, cacheable, evaluated };
+    }
     return {
         decision: Object.freeze({
             allowed: true,

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

@@ -10,6 +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";
 /** Options shared by the permission middleware. */
 export interface AuthorizeMiddlewareOptions extends DeniedResponseOptions {
     /**
@@ -30,13 +31,18 @@ export interface AuthorizeMiddlewareOptions extends DeniedResponseOptions {
     readonly forwardSignal?: boolean;
     /** Builds per-request metadata for conditions and policies. */
     readonly extractMetadata?: (context: HttpMiddlewareContext) => Record<string, unknown> | undefined;
+    /** Reports a failure the guard turned into a denial (a failed resource load). */
+    readonly onError?: (error: unknown, source: string) => void;
 }
 /** Options for the requirePermission middleware. */
 export interface RequirePermissionMiddlewareOptions extends AuthorizeMiddlewareOptions {
     /** The permission to check (e.g. "post:update"). */
     readonly permission: string;
-    /** Extracts the resource from the request (optional). */
-    readonly extractResource?: (context: HttpMiddlewareContext) => unknown;
+    /**
+     * Loads the resource the permission is checked against (optional). May be
+     * async; it is awaited, and a loader that throws or rejects denies (403).
+     */
+    readonly extractResource?: ResourceExtractor;
 }
 /** Options for {@link createActorMiddleware}. */
 export interface ActorMiddlewareOptions extends AuthorizeMiddlewareOptions {
@@ -72,8 +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 {
-    /** Extracts the resource checked for every permission (optional). */
-    readonly extractResource?: (context: HttpMiddlewareContext) => unknown;
+    /**
+     * Loads the resource checked for every permission (optional). May be
+     * async; it is awaited, and a loader that throws or rejects denies (403).
+     */
+    readonly extractResource?: ResourceExtractor;
     /**
      * `"all"` (default) requires every permission; `"any"` requires one.
      */
@@ -83,7 +92,8 @@ export interface RequirePermissionsMiddlewareOptions extends AuthorizeMiddleware
  * 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.
+ * policy calls and timeouts for an answer that is already decided. An empty
+ * permission list denies in either mode.
  */
 export declare function createRequirePermissionsMiddleware(engine: PermissionEngine, permissions: readonly string[], options?: RequirePermissionsMiddlewareOptions): HttpMiddleware;
 //# sourceMappingURL=httpMiddleware.core.d.ts.map

package/dist/http/httpMiddleware.core.js

@@ -7,6 +7,7 @@
  * @module http/httpMiddleware
  */
 import { createForbiddenResponse, createUnauthorizedResponse, } from "./httpHelpers.js";
+import { loadResource } from "./httpResource.helper.js";
 // ─── State Keys ───────────────────────────────────────────────────────────
 /** State key for the current actor. */
 export const ACTOR_STATE_KEY = "permissions:actor";
@@ -64,8 +65,12 @@ export function createRequirePermissionMiddleware(engine, 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, buildAuthorization(context, options));
+        const loaded = await loadResource(context, options.extractResource, options.onError);
+        if (!loaded.ok) {
+            context.state.set(DECISION_STATE_KEY, loaded.decision);
+            return createForbiddenResponse(loaded.decision, options);
+        }
+        const decision = await engine.check(actor, options.permission, loaded.resource, buildAuthorization(context, options));
         context.state.set(DECISION_STATE_KEY, decision);
         if (!decision.allowed)
             return createForbiddenResponse(decision, options);
@@ -85,7 +90,8 @@ export function authorize(engine, permission, options = {}) {
  * 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.
+ * policy calls and timeouts for an answer that is already decided. An empty
+ * permission list denies in either mode.
  */
 export function createRequirePermissionsMiddleware(engine, permissions, options = {}) {
     const mode = options.mode ?? "all";
@@ -93,7 +99,15 @@ export function createRequirePermissionsMiddleware(engine, permissions, options
         const actor = await resolveActor(context, options);
         if (!actor)
             return createUnauthorizedResponse(options);
-        const resource = options.extractResource?.(context);
+        // An empty list is a configuration error, not a grant: under "all" it
+        // used to fall through to next() for any authenticated actor.
+        if (permissions.length === 0) {
+            return createForbiddenResponse({ allowed: false, reason: "no_permissions", publicReason: "Access denied" }, options);
+        }
+        const loaded = await loadResource(context, options.extractResource, options.onError);
+        if (!loaded.ok)
+            return createForbiddenResponse(loaded.decision, options);
+        const resource = loaded.resource;
         const authorization = buildAuthorization(context, options);
         const results = new Map();
         let lastDenial;

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

@@ -0,0 +1,30 @@
+/**
+ * Resource loading for the permission guards.
+ *
+ * @module http/httpResource.helper
+ */
+import type { PermissionDecision } from "../permissionTypes/index.js";
+import type { HttpMiddlewareContext } from "./httpTypes.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. */
+export type ResourceOutcome = {
+    readonly ok: true;
+    readonly resource: unknown;
+} | {
+    readonly ok: false;
+    readonly decision: PermissionDecision;
+};
+/** The decision recorded when the resource loader fails. */
+export declare const RESOURCE_ERROR_DECISION: PermissionDecision;
+/**
+ * Run the extractor and await it.
+ *
+ * The guard used to hand the engine whatever the extractor returned — for an
+ * async loader, a Promise — so every resource condition saw `undefined`:
+ * deny rules on a locked or foreign resource never fired, and a loader that
+ * rejected let the request through while its rejection went unhandled. A
+ * 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>;
+//# sourceMappingURL=httpResource.helper.d.ts.map

package/dist/http/httpResource.helper.js

@@ -0,0 +1,32 @@
+/**
+ * Resource loading for the permission guards.
+ *
+ * @module http/httpResource.helper
+ */
+/** The decision recorded when the resource loader fails. */
+export const RESOURCE_ERROR_DECISION = Object.freeze({
+    allowed: false,
+    reason: "resource_error",
+    publicReason: "Access denied",
+});
+/**
+ * Run the extractor and await it.
+ *
+ * The guard used to hand the engine whatever the extractor returned — for an
+ * async loader, a Promise — so every resource condition saw `undefined`:
+ * deny rules on a locked or foreign resource never fired, and a loader that
+ * rejected let the request through while its rejection went unhandled. A
+ * loader that throws or rejects now denies; the error goes to `onError`.
+ */
+export async function loadResource(context, extract, onError) {
+    if (!extract)
+        return { ok: true, resource: undefined };
+    try {
+        return { ok: true, resource: await extract(context) };
+    }
+    catch (error) {
+        onError?.(error, "extractResource");
+        return { ok: false, decision: RESOURCE_ERROR_DECISION };
+    }
+}
+//# sourceMappingURL=httpResource.helper.js.map

package/dist/http/httpTypes.d.ts

@@ -16,20 +16,33 @@ export interface HttpMiddlewareContext {
     readonly signal: AbortSignal;
     readonly metadata: Readonly<Record<string, unknown>>;
 }
+/**
+ * A request's headers, params or query as either shape a caller may hold.
+ *
+ * The real `@zudojs/http` request exposes plain frozen objects
+ * (`Readonly<Record<…>>`); this mirror used to say `ReadonlyMap`, so code
+ * written against it called `.get()` on an object that has none. Both shapes
+ * are accepted, and the accessor methods below are the portable way to read.
+ */
+export type HttpRequestBag<V> = ReadonlyMap<string, V> | Readonly<Record<string, V | undefined>>;
 /** HTTP request context from @zudojs/http. */
 export interface HttpRequestContext {
     readonly id: string;
     readonly method: string;
     readonly url: string;
     readonly path: string;
-    readonly headers: ReadonlyMap<string, string>;
-    readonly params: ReadonlyMap<string, string>;
-    readonly query: ReadonlyMap<string, string | readonly string[] | undefined>;
+    readonly headers: HttpRequestBag<string>;
+    readonly params: HttpRequestBag<string>;
+    readonly query: HttpRequestBag<string | readonly string[]>;
+    /** Case-insensitive header lookup, as `@zudojs/http` provides it. */
+    getHeader?(name: string): string | undefined;
+    /** Route parameter lookup, as `@zudojs/http` provides it. */
+    getParam?(name: string): string | undefined;
 }
 /** HTTP response context from @zudojs/http. */
 export interface HttpResponseContext {
     readonly status: number;
-    readonly headers: Headers | Record<string, string>;
+    readonly headers: Headers | Readonly<Record<string, string | readonly string[] | undefined>>;
     readonly body?: unknown;
 }
 /** HTTP middleware state from @zudojs/http. */