@zudojs/permissions 1.1.0 → 1.3.0

package/dist/evaluator/authorizationEngine.js

@@ -5,10 +5,11 @@
  */
 import { evaluate, evaluateWithTrace } from "./evaluator.core.js";
 import { createAbility } from "../ability/ability.core.js";
-import { PermissionDeniedError, InvalidRoleError, } from "../permissionErrors/index.js";
-import { isValidPermission } from "../permission/permission.core.js";
+import { PermissionDeniedError } from "../permissionErrors/index.js";
 import { memoizeRoleLookup } from "../role/roleHierarchy.js";
 import { freezeRoleDefinition } from "../role/roleRegistry.js";
+import { validatePolicy, validateRole, validateRoles, validateRule, } from "./engineSupport/index.js";
+import { observed } from "./engineSupport/index.js";
 function isRoleSource(roles) {
     return (roles !== undefined &&
         !Array.isArray(roles) &&
@@ -19,35 +20,20 @@ function isPolicySource(policies) {
         !Array.isArray(policies) &&
         typeof policies.names === "function");
 }
-/** Rejects a role whose grants could never match. */
-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)) {
-            // A malformed grant can never match, so it is a silent no-op unless
-            // it is rejected here.
-            throw new InvalidRoleError(`Role "${role.name}" grants "${permission}", which is not a valid ` +
-                `"resource:action" permission`);
-        }
-    }
-}
-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);
-    }
+function isImpliedPermissionSource(source) {
+    return (source !== undefined &&
+        typeof source !== "function" &&
+        typeof source.expandImplied === "function");
 }
 /**
  * Create a permission engine.
  */
 export function createPermissionEngine(options) {
     const validateConfiguration = options?.validateConfiguration ?? true;
+    if (validateConfiguration) {
+        for (const rule of options?.rules ?? [])
+            validateRule(rule);
+    }
     let roleLookup;
     let invalidateRoleCache;
     if (isRoleSource(options?.roles)) {
@@ -81,13 +67,70 @@ export function createPermissionEngine(options) {
     const policyList = policySource
         ? undefined
         : (options?.policies ?? []);
+    if (validateConfiguration)
+        policyList?.forEach(validatePolicy);
+    // A policy source is read lazily, so its validation is lazy too. Each
+    // definition is checked once; a malformed one makes the check throw, which
+    // never reads as an allow.
+    const validatedPolicies = new WeakSet();
     const resolvePolicies = () => {
         if (!policySource)
             return policyList ?? [];
         return policySource
             .names()
             .map((name) => policySource.get(name))
-            .filter((policy) => policy !== undefined);
+            .filter((policy) => policy !== undefined)
+            .map((policy) => {
+            if (validateConfiguration && !validatedPolicies.has(policy)) {
+                validatePolicy(policy);
+                validatedPolicies.add(policy);
+            }
+            return policy;
+        });
+    };
+    // Every change to the configuration bumps the generation, which is part
+    // of every decision-cache key: an entry written under an older role or
+    // policy set can no longer be found, whatever cache adapter is in use.
+    let generation = 0;
+    const invalidateConfiguration = () => {
+        generation += 1;
+        invalidateRoleCache();
+        const cleared = options?.cache?.clear?.();
+        cleared?.catch((error) => {
+            options?.onError?.(error, "PermissionCache.clear");
+        });
+    };
+    if (isRoleSource(options?.roles)) {
+        options.roles.subscribe?.(invalidateConfiguration);
+    }
+    policySource?.subscribe?.(invalidateConfiguration);
+    // The third registry the README wires in. Without this, revoking an
+    // implication left every decision it granted in the cache for the full TTL
+    // — `skipCache: true` said "deny" while `can()` kept saying "allow".
+    const impliedSource = isImpliedPermissionSource(options?.expandImplied)
+        ? options.expandImplied
+        : undefined;
+    const expandImplied = impliedSource
+        ? (permission) => impliedSource.expandImplied(permission)
+        : options?.expandImplied;
+    const impliedWatched = impliedSource?.subscribe?.(invalidateConfiguration) !== undefined;
+    // Two inputs the cache key cannot describe. An implication source that
+    // cannot announce a change, and a resolver reading state the engine does
+    // not own, both make a cached allow outlive the grant behind it — so the
+    // decision is not cached at all unless the caller closes the gap.
+    const impliedUnwatched = expandImplied !== undefined && !impliedWatched;
+    const resolverConfigured = options?.permissionResolver !== undefined ||
+        options?.roleResolver !== undefined;
+    const resolverCacheKey = options?.resolverCacheKey;
+    const cacheScope = (actor) => {
+        if (impliedUnwatched)
+            return undefined;
+        if (!resolverConfigured)
+            return `g${generation}`;
+        if (!resolverCacheKey)
+            return undefined;
+        const scope = resolverCacheKey(actor);
+        return scope === undefined ? undefined : `g${generation}|r${scope}`;
     };
     // One live view over the configuration. `policies` is a getter so a
     // registry-backed engine re-reads the registry on every evaluation — an
@@ -106,40 +149,15 @@ export function createPermissionEngine(options) {
         cacheTtlMs: options?.cacheTtlMs,
         permissionResolver: options?.permissionResolver,
         roleResolver: options?.roleResolver,
-        expandImplied: options?.expandImplied,
+        expandImplied,
         onError: options?.onError,
+        cacheScope,
     };
     const evaluatorOptions = () => liveOptions;
     const emitter = options?.emitter;
-    /**
-     * Runs a check and emits an audit event whichever way it ends — including
-     * when it throws. An authorization trail that records only the successful
-     * paths is not a trail.
-     */
-    async function runCheck(actor, permission, resource, authOptions) {
-        const start = performance.now();
-        let decision;
-        let failure;
-        try {
-            decision = await evaluate(actor, permission, resource, evaluatorOptions(), authOptions);
-            return decision;
-        }
-        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,
-            });
-        }
+    /** Runs a check and emits an audit event whichever way it ends. */
+    function runCheck(actor, permission, resource, authOptions) {
+        return observed(emitter, actor, permission, resource, () => evaluate(actor, permission, resource, evaluatorOptions(), authOptions), (decision) => decision);
     }
     return {
         async can(actor, permission, resource, authOptions) {
@@ -163,7 +181,7 @@ export function createPermissionEngine(options) {
             }
         },
         async explain(actor, permission, resource, authOptions) {
-            return evaluateWithTrace(actor, permission, resource, evaluatorOptions(), authOptions);
+            return observed(emitter, actor, permission, resource, () => evaluateWithTrace(actor, permission, resource, evaluatorOptions(), authOptions), (result) => result.decision);
         },
         createAbility(actor) {
             return createAbility(actor, evaluatorOptions(), emitter);
@@ -172,18 +190,8 @@ export function createPermissionEngine(options) {
             await options?.cache?.invalidateActor(actorId);
         },
         invalidateRoles() {
-            invalidateRoleCache();
+            invalidateConfiguration();
         },
     };
 }
-/** Best-effort resource type for an audit event. */
-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;
-}
 //# sourceMappingURL=authorizationEngine.js.map

package/dist/evaluator/engineSupport/authorizationEngine.validation.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 type { PermissionPolicyDefinition, PermissionRule, RoleDefinition } from "../../permissionTypes/index.js";
+/**
+ * The first `resource:action` pair a rule names that is not a valid
+ * permission pattern, or `undefined` when every pair is valid.
+ */
+export declare function invalidRulePattern(rule: PermissionRule): string | undefined;
+/**
+ * Reject a rule whose resource or action could never match.
+ *
+ * @throws {InvalidPermissionError} naming the offending pair.
+ */
+export declare function validateRule(rule: PermissionRule): void;
+/**
+ * Reject a policy scoped to a pattern that could never match.
+ *
+ * @throws {InvalidPermissionError} naming the offending pattern.
+ */
+export declare function validatePolicy(policy: PermissionPolicyDefinition): void;
+/**
+ * Reject a role whose grants or rules could never match.
+ *
+ * @throws {InvalidRoleError} naming the role and the offending pattern.
+ */
+export declare function validateRole(role: RoleDefinition): void;
+/** Validate a role list, rejecting duplicates as well. */
+export declare function validateRoles(roles: readonly RoleDefinition[]): void;
+//# sourceMappingURL=authorizationEngine.validation.d.ts.map

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,28 @@
+/**
+ * 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.
+ * - An external resolver reads state the key knows nothing about, so a
+ *   resolver-backed engine is uncacheable unless it supplies
+ *   `resolverCacheKey`. So is one whose implication source cannot announce a
+ *   change.
+ */
+export declare function decisionCacheKey(actor: PermissionActor, permissionStr: string, resource: unknown, options: EvaluatorOptions, authOptions?: AuthorizationOptions): string | undefined;
+//# sourceMappingURL=evaluator.cacheKey.d.ts.map

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

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ * - An external resolver reads state the key knows nothing about, so a
+ *   resolver-backed engine is uncacheable unless it supplies
+ *   `resolverCacheKey`. So is one whose implication source cannot announce a
+ *   change.
+ */
+export function decisionCacheKey(actor, permissionStr, resource, options, authOptions) {
+    if (!options.cache || authOptions?.skipCache === true)
+        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;
+    // An engine that cannot describe its own configuration for this actor
+    // returns `undefined` here — an external resolver with no
+    // `resolverCacheKey`, or an implication source that cannot announce a
+    // change. Both would otherwise keep answering from a revoked grant.
+    let generation = "";
+    if (options.cacheScope !== undefined) {
+        const scope = options.cacheScope(actor);
+        if (scope === undefined)
+            return undefined;
+        generation = scope;
+    }
+    return permissionCacheKey(actor.id, permissionStr, resourceId, `${generation}${digest}`);
+}
+//# sourceMappingURL=evaluator.cacheKey.js.map

package/dist/evaluator/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,17 @@ 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.
+     *
+     * Returning `undefined` means this decision must not be cached: the engine
+     * uses that for the inputs the key cannot describe — an implication source
+     * that cannot announce a change, and an external resolver with no
+     * `resolverCacheKey`.
+     */
+    readonly cacheScope?: (actor: PermissionActor) => string | undefined;
 }
 /** The permissions and rules an actor holds, once everything is resolved. */
 export interface ResolvedGrants {