@zudojs/permissions 0.1.0 → 1.1.0

package/dist/evaluator/evaluator.core.js

@@ -1,57 +1,277 @@
 /**
- * Core permission evaluator — resolves actor permissions and evaluates rules + policies.
+ * Core permission evaluator.
+ *
+ * One evaluation path, with an optional trace collector. `check` and
+ * `explain` used to be ninety duplicated lines kept in sync by hand — in the
+ * one pair of functions that must agree, since `explain` exists to say why
+ * `check` decided what it did.
+ *
+ * @module evaluator/evaluator
  */
-import { parsePermission, matches } from "../permission/permission.core.js";
+import { parsePermissionSafe, matches } 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 { resolveActorPermissions, evaluatePolicies, } from "./evaluator.pipeline.js";
+import { assertNotAborted, evaluatePolicies, resolveActorGrants, toMetadataMap, } from "./evaluator.pipeline.js";
+import { permissionCacheKey } from "../cache/cache.core.js";
 export { evaluateWithExplain } from "./evaluator.explain.js";
+/** A public message that names nothing internal. */
+const PUBLIC_DENIED = "Access denied";
+function denied(reason, extra) {
+    return Object.freeze({
+        allowed: false,
+        reason,
+        publicReason: PUBLIC_DENIED,
+        ...extra,
+    });
+}
 /**
  * Evaluate a single permission check and return a decision.
+ *
+ * Every failure path denies. An unparsable permission, an unknown role, a
+ * policy that throws or times out — all of them produce a denial with a
+ * reason, never an exception that some outer handler might turn into a pass.
+ * The one exception is cancellation, which throws `AuthorizationAbortedError`
+ * because the caller asked for the work to stop.
  */
-export async function evaluate(actor, permissionStr, resource, options, authOptions) {
-    const permission = parsePermission(permissionStr);
-    if (actor.deniedPermissions) {
-        for (const denied of actor.deniedPermissions) {
-            if (denied === permissionStr ||
-                denied === `${permission.resource}:*` ||
-                denied === "*:*") {
-                return Object.freeze({
-                    allowed: false,
-                    reason: "explicit_deny",
-                    matchedPermission: denied,
+export async function evaluate(actor, permissionStr, resource, options, authOptions, trace) {
+    const signal = authOptions?.signal;
+    assertNotAborted(signal);
+    const permission = parsePermissionSafe(permissionStr);
+    if (!permission) {
+        trace?.push({
+            type: "deny",
+            detail: `Malformed permission: ${permissionStr}`,
+            matched: false,
+        });
+        return denied("invalid_permission");
+    }
+    /* ── Explicit denies ─────────────────────────────────────────────────── */
+    // Denies are checked before the cache is consulted. `deniedPermissions`
+    // travels on the actor object, which is per-request data the cache key
+    // knows nothing about, so a cached allow from an earlier call would
+    // otherwise be served to a caller who has since denied the permission.
+    for (const deny of actor.deniedPermissions ?? []) {
+        // Denies go through the same matcher as grants. Comparing them as exact
+        // strings meant `*:delete` was ignored while `*:delete` as a grant was
+        // honoured — an asymmetry a deny list cannot survive.
+        if (!parsePermissionSafe(deny)) {
+            // A malformed deny can never match, so it would silently grant what it
+            // was written to forbid. Report it rather than dropping it in silence.
+            options.onError?.(new InvalidPermissionError(deny), "Actor.deniedPermissions");
+            trace?.push({
+                type: "deny",
+                detail: `Malformed deny ignored: ${deny}`,
+                matched: false,
+            });
+            continue;
+        }
+        if (matches(deny, permissionStr)) {
+            trace?.push({
+                type: "deny",
+                detail: `Explicit deny: ${deny}`,
+                matched: true,
+            });
+            return denied("explicit_deny", { matchedPermission: deny });
+        }
+    }
+    /* ── 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;
+    if (options.cache && cacheKey) {
+        try {
+            const cached = await options.cache.get(cacheKey);
+            if (cached) {
+                trace?.push({
+                    type: "cache",
+                    detail: `Cache hit: ${cached.allowed ? "allow" : "deny"}`,
+                    matched: cached.allowed,
                 });
+                return cached;
             }
         }
+        catch (error) {
+            options.onError?.(error, "PermissionCache.get");
+        }
     }
-    const allPermissions = resolveActorPermissions(actor, options);
-    const matchingPermissions = allPermissions.filter((p) => matches(p, permissionStr));
-    const rules = matchingPermissions.map((p) => {
-        const parsed = parsePermission(p);
-        return {
+    /* ── Grants ──────────────────────────────────────────────────────────── */
+    const grants = await resolveActorGrants(actor, options, signal);
+    assertNotAborted(signal);
+    for (const role of grants.unknownRoles) {
+        options.onError?.(new Error(`Unknown role "${role}" for actor "${actor.id}"`), "RoleHierarchy");
+        trace?.push({
+            type: "role",
+            detail: `Unknown role: ${role}`,
+            matched: false,
+        });
+    }
+    if (trace) {
+        for (const role of actor.roles ?? []) {
+            trace.push({
+                type: "role",
+                detail: `Role: ${role}`,
+                matched: !grants.unknownRoles.includes(role),
+            });
+        }
+    }
+    const matchedPermissions = grants.permissions.filter((granted) => matches(granted, permissionStr));
+    if (trace) {
+        // Only the grants that bear on this decision. Listing every permission
+        // the actor holds turns a trace into a dump of their whole grant set.
+        for (const granted of matchedPermissions) {
+            trace.push({
+                type: "permission",
+                detail: `Permission: ${granted}`,
+                matched: true,
+            });
+        }
+        if (matchedPermissions.length === 0) {
+            trace.push({
+                type: "permission",
+                detail: `No permission matched "${permissionStr}" among ${grants.permissions.length} granted`,
+                matched: false,
+            });
+        }
+    }
+    /* ── Rules ───────────────────────────────────────────────────────────── */
+    const context = {
+        actor,
+        permission,
+        resource,
+        metadata: toMetadataMap(authOptions?.metadata),
+        signal,
+    };
+    const rules = [
+        ...matchedPermissions.map((granted) => ({
             effect: "allow",
-            action: parsed.action,
-            resource: parsed.resource,
-        };
+            resource: parsePermissionSafe(granted)?.resource ?? granted,
+            action: parsePermissionSafe(granted)?.action ?? "*",
+        })),
+        ...grants.rules,
+    ];
+    const ruleResult = await evaluateRules(findMatchingRules(compileRules(rules), permission), permission, context, {
+        algorithm: options.algorithm,
+        onConditionError: (rule, error) => {
+            options.onError?.(error, `RuleCondition.${rule.name ?? "unnamed"}`);
+        },
+    });
+    if (trace) {
+        for (const rule of ruleResult.applicable) {
+            trace.push({
+                type: "rule",
+                detail: `Rule ${rule.effect}: ${rule.name ?? `${String(rule.resource)}:${String(rule.action)}`}`,
+                matched: true,
+            });
+        }
+    }
+    /* ── Policies ────────────────────────────────────────────────────────── */
+    const outcome = await evaluatePolicies(context, options.policies ?? [], options, authOptions);
+    if (trace) {
+        for (const name of outcome.evaluated) {
+            trace.push({
+                type: "policy",
+                detail: `Policy: ${name}`,
+                matched: outcome.decision?.allowed ?? true,
+            });
+        }
+    }
+    const decision = combine(ruleResult, outcome.decision, permissionStr);
+    /* ── Cache write ─────────────────────────────────────────────────────── */
+    if (options.cache && cacheKey && outcome.cacheable) {
+        try {
+            await options.cache.set(cacheKey, decision, {
+                ttl: options.cacheTtlMs,
+            });
+        }
+        catch (error) {
+            options.onError?.(error, "PermissionCache.set");
+        }
+    }
+    return decision;
+}
+/**
+ * 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`.
+ */
+function combine(ruleResult, policyDecision, permissionStr) {
+    if (policyDecision && !policyDecision.allowed)
+        return policyDecision;
+    const denyRule = !ruleResult.allowed && ruleResult.matchedRule?.effect === "deny"
+        ? ruleResult.matchedRule
+        : undefined;
+    if (denyRule) {
+        return denied("rule_deny", {
+            matchedPermission: permissionStr,
+            ...(denyRule.name ? { policy: denyRule.name } : {}),
+        });
+    }
+    if (ruleResult.allowed) {
+        return Object.freeze({
+            allowed: true,
+            reason: "role_permission",
+            matchedPermission: permissionStr,
+            ...(policyDecision?.policy ? { policy: policyDecision.policy } : {}),
+        });
+    }
+    if (policyDecision?.allowed)
+        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.
+ *
+ * `check` and `explain` share this, so a trace can never describe a decision
+ * other than the one that was made.
+ */
+export async function evaluateWithTrace(actor, permissionStr, resource, options, authOptions) {
+    const steps = [];
+    const decision = await evaluate(actor, permissionStr, resource, options, authOptions, { push: (step) => steps.push(step) });
+    steps.push({
+        type: decision.allowed ? "permission" : "deny",
+        detail: `Decision: ${decision.allowed ? "allow" : "deny"} (${decision.reason ?? "unknown"})`,
+        matched: decision.allowed,
     });
-    const compiled = compileRules(rules);
-    const matching = findMatchingRules(compiled, permission);
-    const ruleResult = evaluateRules(matching, permission);
-    if (!ruleResult.allowed) {
-        const ctx = { actor, permission, resource };
-        const policyResult = await evaluatePolicies(ctx, options.policies ?? [], authOptions);
-        if (policyResult !== null)
-            return policyResult;
-        return Object.freeze({ allowed: false, reason: "no_matching_rule" });
-    }
-    const ctx = { actor, permission, resource };
-    const policyResult = await evaluatePolicies(ctx, options.policies ?? [], authOptions);
-    if (policyResult !== null)
-        return policyResult;
     return Object.freeze({
-        allowed: true,
-        reason: "role_permission",
-        matchedPermission: permissionStr,
+        allowed: decision.allowed,
+        steps: Object.freeze(steps),
+        decision,
     });
 }
 //# sourceMappingURL=evaluator.core.js.map

package/dist/evaluator/evaluator.explain.d.ts

@@ -1,12 +1,15 @@
 /**
- * Permission evaluator with full explain trace.
+ * Permission evaluator with a full explain trace.
  *
- * Records each evaluation step for debugging and auditing.
+ * A thin alias over {@link evaluateWithTrace}: the trace is produced by the
+ * same pass that produces the decision, so the two cannot disagree.
+ *
+ * @module evaluator/evaluator.explain
  */
 import type { PermissionActor, ExplainResult, AuthorizationOptions } from "../permissionTypes/index.js";
 import type { EvaluatorOptions } from "./evaluator.pipeline.js";
 /**
- * Evaluate with full explain trace.
+ * Evaluate with a full explain trace.
  */
 export declare function evaluateWithExplain(actor: PermissionActor, permissionStr: string, resource: unknown, options: EvaluatorOptions, authOptions?: AuthorizationOptions): Promise<ExplainResult>;
 //# sourceMappingURL=evaluator.explain.d.ts.map

package/dist/evaluator/evaluator.explain.js

@@ -1,79 +1,16 @@
 /**
- * Permission evaluator with full explain trace.
+ * Permission evaluator with a full explain trace.
  *
- * Records each evaluation step for debugging and auditing.
+ * A thin alias over {@link evaluateWithTrace}: the trace is produced by the
+ * same pass that produces the decision, so the two cannot disagree.
+ *
+ * @module evaluator/evaluator.explain
  */
-import { parsePermission, matches } from "../permission/permission.core.js";
-import { compileRules, findMatchingRules } from "../rule/ruleCompiler.js";
-import { evaluateRules } from "../rule/rule.core.js";
-import { resolveActorPermissions, evaluatePolicies, } from "./evaluator.pipeline.js";
+import { evaluateWithTrace } from "./evaluator.core.js";
 /**
- * Evaluate with full explain trace.
+ * Evaluate with a full explain trace.
  */
 export async function evaluateWithExplain(actor, permissionStr, resource, options, authOptions) {
-    const permission = parsePermission(permissionStr);
-    const steps = [];
-    if (actor.deniedPermissions) {
-        for (const denied of actor.deniedPermissions) {
-            if (denied === permissionStr ||
-                denied === `${permission.resource}:*` ||
-                denied === "*:*") {
-                steps.push({
-                    type: "deny",
-                    detail: `Explicit deny: ${denied}`,
-                    matched: true,
-                });
-                return Object.freeze({ allowed: false, steps });
-            }
-        }
-    }
-    const allPermissions = resolveActorPermissions(actor, options);
-    if (actor.roles) {
-        for (const role of actor.roles) {
-            steps.push({ type: "role", detail: `Role: ${role}`, matched: true });
-        }
-    }
-    const matchingPermissions = allPermissions.filter((p) => matches(p, permissionStr));
-    const rules = matchingPermissions.map((p) => {
-        const parsed = parsePermission(p);
-        return {
-            effect: "allow",
-            action: parsed.action,
-            resource: parsed.resource,
-        };
-    });
-    const compiled = compileRules(rules);
-    const matching = findMatchingRules(compiled, permission);
-    const ruleResult = evaluateRules(matching, permission);
-    for (const perm of allPermissions) {
-        const matched = matches(perm, permissionStr);
-        steps.push({ type: "permission", detail: `Permission: ${perm}`, matched });
-    }
-    if (!ruleResult.allowed) {
-        const ctx = { actor, permission, resource };
-        const policyResult = await evaluatePolicies(ctx, options.policies ?? [], authOptions);
-        if (policyResult !== null) {
-            steps.push({
-                type: "policy",
-                detail: `Policy: ${policyResult.reason ?? "unknown"}`,
-                matched: policyResult.allowed,
-            });
-            return Object.freeze({ allowed: policyResult.allowed, steps });
-        }
-        steps.push({ type: "deny", detail: "No matching rule", matched: false });
-        return Object.freeze({ allowed: false, steps });
-    }
-    const ctx = { actor, permission, resource };
-    const policyResult = await evaluatePolicies(ctx, options.policies ?? [], authOptions);
-    if (policyResult !== null) {
-        steps.push({
-            type: "policy",
-            detail: `Policy: ${policyResult.reason ?? "unknown"}`,
-            matched: policyResult.allowed,
-        });
-        return Object.freeze({ allowed: policyResult.allowed, steps });
-    }
-    steps.push({ type: "permission", detail: "Rule matched", matched: true });
-    return Object.freeze({ allowed: true, steps });
+    return evaluateWithTrace(actor, permissionStr, resource, options, authOptions);
 }
 //# sourceMappingURL=evaluator.explain.js.map

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

@@ -3,26 +3,87 @@
  *
  * @module evaluator/evaluator.pipeline
  */
-import type { PermissionActor, PermissionContext, PermissionDecision, PermissionPolicyDefinition, AuthorizationOptions } from "../permissionTypes/index.js";
+import type { PermissionActor, PermissionContext, PermissionDecision, PermissionPolicyDefinition, PermissionRule, PermissionCache, PermissionResolver, RoleDefinition, RoleResolver, RuleCombiningAlgorithm, AuthorizationOptions } from "../permissionTypes/index.js";
 /** Configuration for the evaluator. */
 export interface EvaluatorOptions {
     /** Function to look up a role definition by name. */
-    readonly getRole?: (name: string) => {
-        readonly name: string;
-        readonly permissions: readonly string[];
-        readonly inherits?: readonly string[];
-    } | undefined;
+    readonly getRole?: (name: string) => RoleDefinition | undefined;
     /** Registered policies. */
     readonly policies?: readonly PermissionPolicyDefinition[];
+    /** Static rules, evaluated alongside the actor's permissions. */
+    readonly rules?: readonly PermissionRule[];
     /** Default timeout for async policy evaluation (ms). */
     readonly policyTimeout?: number;
+    /** How competing rules combine. Default: `"deny-overrides"`. */
+    readonly algorithm?: RuleCombiningAlgorithm;
+    /** Decision cache. */
+    readonly cache?: PermissionCache;
+    /** Time-to-live for cached decisions, in ms. */
+    readonly cacheTtlMs?: number;
+    /** Loads additional rules for an actor from an external source. */
+    readonly permissionResolver?: PermissionResolver;
+    /** Loads additional roles for an actor from an external source. */
+    readonly roleResolver?: RoleResolver;
+    /**
+     * Expands a permission into the ones it implies, so that granting
+     * `post:admin` can carry `post:read` with it.
+     */
+    readonly expandImplied?: (permission: string) => readonly string[];
+    /** Reports a failure that authorization swallowed to stay fail-closed. */
+    readonly onError?: (error: unknown, source: string) => void;
 }
+/** The permissions and rules an actor holds, once everything is resolved. */
+export interface ResolvedGrants {
+    readonly permissions: readonly string[];
+    readonly rules: readonly PermissionRule[];
+    /** Roles that could not be resolved. Their permissions are absent. */
+    readonly unknownRoles: readonly string[];
+}
+/** Throws if the caller has cancelled the check. */
+export declare function assertNotAborted(signal?: AbortSignal): void;
+/** Normalizes caller-supplied metadata into the map conditions read. */
+export declare function toMetadataMap(metadata: AuthorizationOptions["metadata"]): ReadonlyMap<string, unknown> | undefined;
 /**
- * Resolve all permissions for an actor (direct + role-based).
+ * 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 declare function resolveActorGrants(actor: PermissionActor, options: EvaluatorOptions, signal?: AbortSignal): Promise<ResolvedGrants>;
+/**
+ * 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 declare function resolveActorPermissions(actor: PermissionActor, options: EvaluatorOptions): readonly string[];
+/** Policies that apply to a permission, most important first. */
+export declare function selectPolicies(policies: readonly PermissionPolicyDefinition[], permissionStr: string): readonly PermissionPolicyDefinition[];
+/** The outcome of running the applicable policies. */
+export interface PolicyOutcome {
+    /** `null` when no policy applied. */
+    readonly decision: PermissionDecision | null;
+    /** Whether every policy that ran allows the result to be cached. */
+    readonly cacheable: boolean;
+    readonly evaluated: readonly string[];
+}
 /**
- * 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 declare function evaluatePolicies(context: PermissionContext, policies: readonly PermissionPolicyDefinition[], options: EvaluatorOptions, authOptions?: AuthorizationOptions): Promise<PolicyOutcome>;
+/**
+ * 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.
  */
-export declare function evaluatePolicies(context: PermissionContext, policies: readonly PermissionPolicyDefinition[], authOptions?: AuthorizationOptions): Promise<PermissionDecision | null>;
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number | undefined, policyName?: string): Promise<T>;
 //# sourceMappingURL=evaluator.pipeline.d.ts.map