@zudojs/permissions 0.1.0 → 1.1.0

package/dist/conditions/conditions.core.d.ts

@@ -1,6 +1,9 @@
 /**
  * Condition combinators for composing authorization policies.
  *
+ * Conditions are evaluated by the rule engine: attach one to a
+ * `PermissionRule` and the rule applies only when it returns `true`.
+ *
  * @module conditions/conditions
  */
 import type { PermissionConditionFn } from "../permissionTypes/index.js";
@@ -33,8 +36,21 @@ export declare function isOwner(ownerField?: string): PermissionConditionFn;
 /**
  * Enforce tenant isolation — actor and resource must share the same tenant.
  *
- * @param actorTenantField - Field on actor metadata holding tenant ID. Defaults to "tenantId".
- * @param resourceTenantField - Field on resource holding tenant ID. Defaults to "tenantId".
+ * The actor's tenant is read from `context.metadata`, which is supplied per
+ * check through `AuthorizationOptions.metadata`:
+ *
+ * ```ts
+ * engine.check(actor, "invoice:read", invoice, {
+ *   metadata: { tenantId: request.tenantId },
+ * });
+ * ```
+ *
+ * @param actorTenantField - Key in the context metadata holding the actor's tenant. Defaults to "tenantId".
+ * @param resourceTenantField - Field on the resource holding the tenant ID. Defaults to "tenantId".
  */
 export declare function tenantIsolation(actorTenantField?: string, resourceTenantField?: string): PermissionConditionFn;
+/** Check that a value in the context metadata equals an expected value. */
+export declare function metadataEquals(key: string, expected: unknown): PermissionConditionFn;
+/** Check that the resource field matches the expected value. */
+export declare function resourceEquals(field: string, expected: unknown): PermissionConditionFn;
 //# sourceMappingURL=conditions.core.d.ts.map

package/dist/conditions/conditions.core.js

@@ -1,6 +1,9 @@
 /**
  * Condition combinators for composing authorization policies.
  *
+ * Conditions are evaluated by the rule engine: attach one to a
+ * `PermissionRule` and the rule applies only when it returns `true`.
+ *
  * @module conditions/conditions
  */
 /**
@@ -45,6 +48,22 @@ export function always() {
 export function never() {
     return () => false;
 }
+/** Compares two identifiers that may differ in type across a boundary. */
+function sameId(left, right) {
+    if (left === undefined || left === null)
+        return false;
+    if (right === undefined || right === null)
+        return false;
+    if (typeof left === typeof right)
+        return left === right;
+    // A numeric id from a database row against a string id from a token is the
+    // common case, and a strict comparison silently denies.
+    if ((typeof left === "string" || typeof left === "number") &&
+        (typeof right === "string" || typeof right === "number")) {
+        return String(left) === String(right);
+    }
+    return false;
+}
 /**
  * Check that the actor owns the resource.
  *
@@ -55,24 +74,45 @@ export function isOwner(ownerField = "ownerId") {
         if (!context.resource || typeof context.resource !== "object")
             return false;
         const resource = context.resource;
-        const ownerId = resource[ownerField];
-        return ownerId === context.actor.id;
+        return sameId(resource[ownerField], context.actor.id);
     };
 }
 /**
  * Enforce tenant isolation — actor and resource must share the same tenant.
  *
- * @param actorTenantField - Field on actor metadata holding tenant ID. Defaults to "tenantId".
- * @param resourceTenantField - Field on resource holding tenant ID. Defaults to "tenantId".
+ * The actor's tenant is read from `context.metadata`, which is supplied per
+ * check through `AuthorizationOptions.metadata`:
+ *
+ * ```ts
+ * engine.check(actor, "invoice:read", invoice, {
+ *   metadata: { tenantId: request.tenantId },
+ * });
+ * ```
+ *
+ * @param actorTenantField - Key in the context metadata holding the actor's tenant. Defaults to "tenantId".
+ * @param resourceTenantField - Field on the resource holding the tenant ID. Defaults to "tenantId".
  */
 export function tenantIsolation(actorTenantField = "tenantId", resourceTenantField = "tenantId") {
     return (context) => {
         const actorTenant = context.metadata?.get(actorTenantField);
+        if (actorTenant === undefined || actorTenant === null)
+            return false;
         if (!context.resource || typeof context.resource !== "object")
             return false;
         const resource = context.resource;
-        const resourceTenant = resource[resourceTenantField];
-        return actorTenant !== undefined && actorTenant === resourceTenant;
+        return sameId(actorTenant, resource[resourceTenantField]);
+    };
+}
+/** Check that a value in the context metadata equals an expected value. */
+export function metadataEquals(key, expected) {
+    return (context) => context.metadata?.get(key) === expected;
+}
+/** Check that the resource field matches the expected value. */
+export function resourceEquals(field, expected) {
+    return (context) => {
+        if (!context.resource || typeof context.resource !== "object")
+            return false;
+        return context.resource[field] === expected;
     };
 }
 //# sourceMappingURL=conditions.core.js.map

package/dist/conditions/index.d.ts

@@ -3,5 +3,5 @@
  *
  * @module conditions
  */
-export { allOf, anyOf, not, always, never, isOwner, tenantIsolation, } from "./conditions.core.js";
+export { allOf, anyOf, not, always, never, isOwner, tenantIsolation, metadataEquals, resourceEquals, } from "./conditions.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/conditions/index.js

@@ -3,5 +3,5 @@
  *
  * @module conditions
  */
-export { allOf, anyOf, not, always, never, isOwner, tenantIsolation, } from "./conditions.core.js";
+export { allOf, anyOf, not, always, never, isOwner, tenantIsolation, metadataEquals, resourceEquals, } from "./conditions.core.js";
 //# sourceMappingURL=index.js.map

package/dist/evaluator/authorizationEngine.d.ts

@@ -3,17 +3,55 @@
  *
  * @module evaluator/authorizationEngine
  */
-import type { PermissionActor, PermissionDecision, ExplainResult, PermissionPolicyDefinition, AuthorizationOptions } from "../permissionTypes/index.js";
-import type { RoleDefinition } from "../permissionTypes/index.js";
+import type { PermissionActor, PermissionDecision, ExplainResult, PermissionRule, PermissionPolicyDefinition, PermissionCache, PermissionResolver, RoleResolver, RoleDefinition, RuleCombiningAlgorithm, AuthorizationOptions } from "../permissionTypes/index.js";
 import { type Ability } from "../ability/ability.core.js";
+import type { PermissionEventEmitter } from "../observability/observability.core.js";
+/** Anything the engine will accept as its source of roles. */
+export interface RoleSource {
+    get(name: string): RoleDefinition | undefined;
+}
+/** Anything the engine will accept as its source of policies. */
+export interface PolicySource {
+    names(): readonly string[];
+    get(name: string): PermissionPolicyDefinition | undefined;
+}
 /** Configuration for the permission engine. */
 export interface PermissionEngineOptions {
-    /** Roles available to the engine. */
-    readonly roles?: readonly RoleDefinition[];
-    /** Policies to evaluate during authorization. */
-    readonly policies?: readonly PermissionPolicyDefinition[];
+    /**
+     * Roles available to the engine — an array, or a registry created with
+     * `createRoleRegistry()`.
+     */
+    readonly roles?: readonly RoleDefinition[] | RoleSource;
+    /**
+     * Policies to evaluate during authorization — an array, or a registry
+     * created with `createPolicyRegistry()`.
+     */
+    readonly policies?: readonly PermissionPolicyDefinition[] | PolicySource;
+    /** 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;
+    /** Caches decisions. Create one with `createMemoryPermissionCache()`. */
+    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 permissions it implies. */
+    readonly expandImplied?: (permission: string) => readonly string[];
+    /** Emits an event for every completed check, including failures. */
+    readonly emitter?: PermissionEventEmitter;
+    /** Reports a failure authorization swallowed to stay fail-closed. */
+    readonly onError?: (error: unknown, source: string) => void;
+    /**
+     * Rejects malformed configuration at construction instead of letting a
+     * grant that can never match sit in the role table. Default: `true`.
+     */
+    readonly validateConfiguration?: boolean;
 }
 /**
  * The public permission engine API.
@@ -39,6 +77,10 @@ export interface PermissionEngine {
      * Create a pre-resolved Ability for an actor.
      */
     createAbility(actor: PermissionActor): Ability;
+    /** Drop cached decisions for one actor. */
+    invalidateActor(actorId: string): Promise<void>;
+    /** Re-read the role source, discarding the memoized lookups. */
+    invalidateRoles(): void;
 }
 /**
  * Create a permission engine.

package/dist/evaluator/authorizationEngine.js

@@ -3,47 +3,187 @@
  *
  * @module evaluator/authorizationEngine
  */
-import { evaluate, evaluateWithExplain } from "./evaluator.core.js";
+import { evaluate, evaluateWithTrace } from "./evaluator.core.js";
 import { createAbility } from "../ability/ability.core.js";
-import { PermissionDeniedError } from "../permissionErrors/index.js";
+import { PermissionDeniedError, InvalidRoleError, } from "../permissionErrors/index.js";
+import { isValidPermission } from "../permission/permission.core.js";
+import { memoizeRoleLookup } from "../role/roleHierarchy.js";
+import { freezeRoleDefinition } from "../role/roleRegistry.js";
+function isRoleSource(roles) {
+    return (roles !== undefined &&
+        !Array.isArray(roles) &&
+        typeof roles.get === "function");
+}
+function isPolicySource(policies) {
+    return (policies !== undefined &&
+        !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);
+    }
+}
 /**
  * Create a permission engine.
  */
 export function createPermissionEngine(options) {
-    const roleMap = new Map();
-    if (options?.roles) {
-        for (const role of options.roles) {
-            roleMap.set(role.name, role);
-        }
+    const validateConfiguration = options?.validateConfiguration ?? true;
+    let roleLookup;
+    let invalidateRoleCache;
+    if (isRoleSource(options?.roles)) {
+        const source = options.roles;
+        // A role source is looked up lazily, so `validateConfiguration` has to be
+        // applied lazily too. Checking only the array form left a registry-backed
+        // engine accepting grants that can never match — the exact silent no-op
+        // the option exists to prevent.
+        const memo = memoizeRoleLookup((name) => {
+            const role = source.get(name);
+            if (role && validateConfiguration)
+                validateRole(role);
+            return role;
+        });
+        roleLookup = memo.lookup;
+        invalidateRoleCache = memo.invalidate;
     }
-    const evaluatorOptions = {
-        getRole: (name) => roleMap.get(name),
-        policies: options?.policies,
+    else {
+        const list = (options?.roles ?? []);
+        if (validateConfiguration)
+            validateRoles(list);
+        // Copy each role, so a caller still holding the arrays it passed in
+        // cannot widen a grant after validation has run.
+        const roleMap = new Map(list.map((role) => [role.name, freezeRoleDefinition(role)]));
+        roleLookup = (name) => roleMap.get(name);
+        invalidateRoleCache = () => { };
+    }
+    const policySource = isPolicySource(options?.policies)
+        ? options.policies
+        : undefined;
+    const policyList = policySource
+        ? undefined
+        : (options?.policies ?? []);
+    const resolvePolicies = () => {
+        if (!policySource)
+            return policyList ?? [];
+        return policySource
+            .names()
+            .map((name) => policySource.get(name))
+            .filter((policy) => policy !== undefined);
+    };
+    // One live view over the configuration. `policies` is a getter so a
+    // registry-backed engine re-reads the registry on every evaluation — an
+    // Ability used to capture a snapshot of the policy list when it was
+    // created, so a policy defined afterwards was enforced by `engine.can()`
+    // and ignored by `ability.can()` for the same actor.
+    const liveOptions = {
+        getRole: (name) => roleLookup(name),
+        get policies() {
+            return resolvePolicies();
+        },
+        rules: options?.rules,
         policyTimeout: options?.policyTimeout,
+        algorithm: options?.algorithm,
+        cache: options?.cache,
+        cacheTtlMs: options?.cacheTtlMs,
+        permissionResolver: options?.permissionResolver,
+        roleResolver: options?.roleResolver,
+        expandImplied: options?.expandImplied,
+        onError: options?.onError,
     };
+    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,
+            });
+        }
+    }
     return {
         async can(actor, permission, resource, authOptions) {
-            const decision = await evaluate(actor, permission, resource, evaluatorOptions, authOptions);
+            const decision = await runCheck(actor, permission, resource, authOptions);
             return decision.allowed;
         },
         async check(actor, permission, resource, authOptions) {
-            return evaluate(actor, permission, resource, evaluatorOptions, authOptions);
+            return runCheck(actor, permission, resource, authOptions);
         },
         async authorize(actor, permission, resource, authOptions) {
-            const decision = await evaluate(actor, permission, resource, evaluatorOptions, authOptions);
+            const decision = await runCheck(actor, permission, resource, authOptions);
             if (!decision.allowed) {
-                throw new PermissionDeniedError(decision.reason ?? "Access denied", {
+                // The public message names nothing internal; the reason and the
+                // policy travel in metadata for the log.
+                throw new PermissionDeniedError(decision.publicReason ?? "Access denied", {
                     actorId: actor.id,
                     permission,
+                    reason: decision.reason,
+                    policy: decision.policy,
                 });
             }
         },
         async explain(actor, permission, resource, authOptions) {
-            return evaluateWithExplain(actor, permission, resource, evaluatorOptions, authOptions);
+            return evaluateWithTrace(actor, permission, resource, evaluatorOptions(), authOptions);
         },
         createAbility(actor) {
-            return createAbility(actor, evaluatorOptions);
+            return createAbility(actor, evaluatorOptions(), emitter);
+        },
+        async invalidateActor(actorId) {
+            await options?.cache?.invalidateActor(actorId);
+        },
+        invalidateRoles() {
+            invalidateRoleCache();
         },
     };
 }
+/** 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/evaluator.core.d.ts

@@ -1,11 +1,35 @@
 /**
- * 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 type { PermissionActor, PermissionDecision, AuthorizationOptions } from "../permissionTypes/index.js";
-import type { EvaluatorOptions } from "./evaluator.pipeline.js";
+import type { PermissionActor, PermissionDecision, ExplainStep, ExplainResult, AuthorizationOptions } from "../permissionTypes/index.js";
+import { type EvaluatorOptions } from "./evaluator.pipeline.js";
 export { evaluateWithExplain } from "./evaluator.explain.js";
+/** Collects the steps that explain a decision. */
+export interface TraceCollector {
+    push(step: ExplainStep): void;
+}
 /**
  * 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 declare function evaluate(actor: PermissionActor, permissionStr: string, resource: unknown, options: EvaluatorOptions, authOptions?: AuthorizationOptions): Promise<PermissionDecision>;
+export declare function evaluate(actor: PermissionActor, permissionStr: string, resource: unknown, options: EvaluatorOptions, authOptions?: AuthorizationOptions, trace?: TraceCollector): Promise<PermissionDecision>;
+/**
+ * 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 declare function evaluateWithTrace(actor: PermissionActor, permissionStr: string, resource: unknown, options: EvaluatorOptions, authOptions?: AuthorizationOptions): Promise<ExplainResult>;
 //# sourceMappingURL=evaluator.core.d.ts.map