skills/plugins/document-navigator/docs/identity/auth/permissions/README.md

@suaveplan/permissions - Full RBAC/ABAC permissions engine: Ability/AbilityBuilder, RoleManager, PolicyEngine, PermissionCache, conditions, and pluggable storage adapters

Summary

Full RBAC/ABAC permissions engine for Suaveplan. Ships role management, policy evaluation, CASL-inspired ability builder, TTL permission cache, condition evaluation, and framework-agnostic middleware.

Documentation tree

• adapter-interface — (no submodules)
  • adapter-interface — (no submodules)
• memory — (no submodules)
  • memory — (no submodules)
• permission-cache — (no submodules)
  • permission-cache — (no submodules)
• condition-matcher — (no submodules)
  • condition-matcher — (no submodules)
• field-matcher — (no submodules)
  • field-matcher — (no submodules)
• subject-detector — (no submodules)
  • subject-detector — (no submodules)
• ability — (no submodules)
  • ability — (no submodules)
• ability-builder — (no submodules)
  • ability-builder — (no submodules)
• permission-manager — (no submodules)
  • permission-manager — (no submodules)
• policy-engine — (no submodules)
  • policy-engine — (no submodules)
• role-manager — (no submodules)
  • role-manager — (no submodules)
• rule — (no submodules)
  • rule — (no submodules)
• errors — (no submodules)
  • permission-error — (no submodules)
• events — (no submodules)
  • permission-events — (no submodules)
• permission-middleware — (no submodules)
  • permission-middleware — (no submodules)
• role-presets — (no submodules)
  • role-presets — (no submodules)
• schemas — (no submodules)
  • permissions.schemas — (no submodules)

- [adapter-interface](./src/adapters/adapter-interface/adapter-interface.md) — _(no submodules)_- [memory](./src/adapters/memory/memory.md) — _(no submodules)_- [memory](./src/adapters/memory/memory.md) — _(no submodules)_- [permission-cache](./src/cache/permission-cache/permission-cache.md) — _(no submodules)_- [permission-cache](./src/cache/permission-cache/permission-cache.md) — _(no submodules)_- [condition-matcher](./src/conditions/condition-matcher/condition-matcher.md) — _(no submodules)_- [condition-matcher](./src/conditions/condition-matcher/condition-matcher.md) — _(no submodules)_- [field-matcher](./src/conditions/field-matcher/field-matcher.md) — _(no submodules)_- [field-matcher](./src/conditions/field-matcher/field-matcher.md) — _(no submodules)_- [subject-detector](./src/conditions/subject-detector/subject-detector.md) — _(no submodules)_- [subject-detector](./src/conditions/subject-detector/subject-detector.md) — _(no submodules)_- [ability](./src/core/ability/ability.md) — _(no submodules)_- [ability](./src/core/ability/ability.md) — _(no submodules)_- [ability-builder](./src/core/ability-builder/ability-builder.md) — _(no submodules)_- [ability-builder](./src/core/ability-builder/ability-builder.md) — _(no submodules)_- [permission-manager](./src/core/permission-manager/permission-manager.md) — _(no submodules)_- [permission-manager](./src/core/permission-manager/permission-manager.md) — _(no submodules)_- [policy-engine](./src/core/policy-engine/policy-engine.md) — _(no submodules)_- [policy-engine](./src/core/policy-engine/policy-engine.md) — _(no submodules)_- [role-manager](./src/core/role-manager/role-manager.md) — _(no submodules)_- [role-manager](./src/core/role-manager/role-manager.md) — _(no submodules)_- [rule](./src/core/rule/rule.md) — _(no submodules)_- [rule](./src/core/rule/rule.md) — _(no submodules)_- [errors](./src/errors/permission-error.md) — _(no submodules)_- [permission-error](./src/errors/permission-error.md) — _(no submodules)_- [events](./src/events/permission-events.md) — _(no submodules)_- [permission-events](./src/events/permission-events.md) — _(no submodules)_- [permission-middleware](./src/middleware/permission-middleware/permission-middleware.md) — _(no submodules)_- [permission-middleware](./src/middleware/permission-middleware/permission-middleware.md) — _(no submodules)_- [role-presets](./src/presets/role-presets/role-presets.md) — _(no submodules)_- [role-presets](./src/presets/role-presets/role-presets.md) — _(no submodules)_- [schemas](./src/schemas/permissions.schemas.md) — _(no submodules)_- [permissions.schemas](./src/schemas/permissions.schemas.md) — _(no submodules)_- [adapter-interface](./src/adapters/adapter-interface/adapter-interface.md) — _(no submodules)_- [memory](./src/adapters/memory/memory.md) — _(no submodules)_- [memory](./src/adapters/memory/memory.md) — _(no submodules)_- [permission-cache](./src/cache/permission-cache/permission-cache.md) — _(no submodules)_- [permission-cache](./src/cache/permission-cache/permission-cache.md) — _(no submodules)_- [condition-matcher](./src/conditions/condition-matcher/condition-matcher.md) — _(no submodules)_- [condition-matcher](./src/conditions/condition-matcher/condition-matcher.md) — _(no submodules)_- [field-matcher](./src/conditions/field-matcher/field-matcher.md) — _(no submodules)_- [field-matcher](./src/conditions/field-matcher/field-matcher.md) — _(no submodules)_- [subject-detector](./src/conditions/subject-detector/subject-detector.md) — _(no submodules)_- [subject-detector](./src/conditions/subject-detector/subject-detector.md) — _(no submodules)_- [ability](./src/core/ability/ability.md) — _(no submodules)_- [ability](./src/core/ability/ability.md) — _(no submodules)_- [ability-builder](./src/core/ability-builder/ability-builder.md) — _(no submodules)_- [ability-builder](./src/core/ability-builder/ability-builder.md) — _(no submodules)_- [permission-manager](./src/core/permission-manager/permission-manager.md) — _(no submodules)_- [permission-manager](./src/core/permission-manager/permission-manager.md) — _(no submodules)_- [policy-engine](./src/core/policy-engine/policy-engine.md) — _(no submodules)_- [policy-engine](./src/core/policy-engine/policy-engine.md) — _(no submodules)_- [role-manager](./src/core/role-manager/role-manager.md) — _(no submodules)_- [role-manager](./src/core/role-manager/role-manager.md) — _(no submodules)_- [rule](./src/core/rule/rule.md) — _(no submodules)_- [rule](./src/core/rule/rule.md) — _(no submodules)_- [errors](./src/errors/permission-error.md) — _(no submodules)_- [permission-error](./src/errors/permission-error.md) — _(no submodules)_- [events](./src/events/permission-events.md) — _(no submodules)_- [permission-events](./src/events/permission-events.md) — _(no submodules)_- [permission-middleware](./src/middleware/permission-middleware/permission-middleware.md) — _(no submodules)_- [permission-middleware](./src/middleware/permission-middleware/permission-middleware.md) — _(no submodules)_- [role-presets](./src/presets/role-presets/role-presets.md) — _(no submodules)_- [role-presets](./src/presets/role-presets/role-presets.md) — _(no submodules)_- [schemas](./src/schemas/permissions.schemas.md) — _(no submodules)_- [permissions.schemas](./src/schemas/permissions.schemas.md) — _(no submodules)_- [adapter-interface](./src/adapters/adapter-interface/adapter-interface.md) — _(no submodules)_- [memory](./src/adapters/memory/memory.md) — _(no submodules)_- [memory](./src/adapters/memory/memory.md) — _(no submodules)_- [permission-cache](./src/cache/permission-cache/permission-cache.md) — _(no submodules)_- [permission-cache](./src/cache/permission-cache/permission-cache.md) — _(no submodules)_- [condition-matcher](./src/conditions/condition-matcher/condition-matcher.md) — _(no submodules)_- [condition-matcher](./src/conditions/condition-matcher/condition-matcher.md) — _(no submodules)_- [field-matcher](./src/conditions/field-matcher/field-matcher.md) — _(no submodules)_- [field-matcher](./src/conditions/field-matcher/field-matcher.md) — _(no submodules)_- [subject-detector](./src/conditions/subject-detector/subject-detector.md) — _(no submodules)_- [subject-detector](./src/conditions/subject-detector/subject-detector.md) — _(no submodules)_- [ability](./src/core/ability/ability.md) — _(no submodules)_- [ability](./src/core/ability/ability.md) — _(no submodules)_- [ability-builder](./src/core/ability-builder/ability-builder.md) — _(no submodules)_- [ability-builder](./src/core/ability-builder/ability-builder.md) — _(no submodules)_- [permission-manager](./src/core/permission-manager/permission-manager.md) — _(no submodules)_- [permission-manager](./src/core/permission-manager/permission-manager.md) — _(no submodules)_- [policy-engine](./src/core/policy-engine/policy-engine.md) — _(no submodules)_- [policy-engine](./src/core/policy-engine/policy-engine.md) — _(no submodules)_- [role-manager](./src/core/role-manager/role-manager.md) — _(no submodules)_- [role-manager](./src/core/role-manager/role-manager.md) — _(no submodules)_- [rule](./src/core/rule/rule.md) — _(no submodules)_- [rule](./src/core/rule/rule.md) — _(no submodules)_- [errors](./src/errors/permission-error.md) — _(no submodules)_- [permission-error](./src/errors/permission-error.md) — _(no submodules)_- [events](./src/events/permission-events.md) — _(no submodules)_- [permission-events](./src/events/permission-events.md) — _(no submodules)_- [permission-middleware](./src/middleware/permission-middleware/permission-middleware.md) — _(no submodules)_- [permission-middleware](./src/middleware/permission-middleware/permission-middleware.md) — _(no submodules)_- [role-presets](./src/presets/role-presets/role-presets.md) — _(no submodules)_- [role-presets](./src/presets/role-presets/role-presets.md) — _(no submodules)_- [schemas](./src/schemas/permissions.schemas.md) — _(no submodules)_- [permissions.schemas](./src/schemas/permissions.schemas.md) — _(no submodules)_- [adapter-interface](./src/adapters/adapter-interface/adapter-interface.md) — _(no submodules)_- [memory](./src/adapters/memory/memory.md) — _(no submodules)_ - [memory](./src/adapters/memory/memory.md) — _(no submodules)_- [permission-cache](./src/cache/permission-cache/permission-cache.md) — _(no submodules)_ - [permission-cache](./src/cache/permission-cache/permission-cache.md) — _(no submodules)_- [condition-matcher](./src/conditions/condition-matcher/condition-matcher.md) — _(no submodules)_ - [condition-matcher](./src/conditions/condition-matcher/condition-matcher.md) — _(no submodules)_- [field-matcher](./src/conditions/field-matcher/field-matcher.md) — _(no submodules)_ - [field-matcher](./src/conditions/field-matcher/field-matcher.md) — _(no submodules)_- [subject-detector](./src/conditions/subject-detector/subject-detector.md) — _(no submodules)_ - [subject-detector](./src/conditions/subject-detector/subject-detector.md) — _(no submodules)_- [ability](./src/core/ability/ability.md) — _(no submodules)_ - [ability](./src/core/ability/ability.md) — _(no submodules)_- [ability-builder](./src/core/ability-builder/ability-builder.md) — _(no submodules)_ - [ability-builder](./src/core/ability-builder/ability-builder.md) — _(no submodules)_- [permission-manager](./src/core/permission-manager/permission-manager.md) — _(no submodules)_ - [permission-manager](./src/core/permission-manager/permission-manager.md) — _(no submodules)_- [policy-engine](./src/core/policy-engine/policy-engine.md) — _(no submodules)_ - [policy-engine](./src/core/policy-engine/policy-engine.md) — _(no submodules)_- [role-manager](./src/core/role-manager/role-manager.md) — _(no submodules)_ - [role-manager](./src/core/role-manager/role-manager.md) — _(no submodules)_- [rule](./src/core/rule/rule.md) — _(no submodules)_ - [rule](./src/core/rule/rule.md) — _(no submodules)_- [errors](./src/errors/permission-error.md) — _(no submodules)_ - [permission-error](./src/errors/permission-error.md) — _(no submodules)_- [events](./src/events/permission-events.md) — _(no submodules)_ - [permission-events](./src/events/permission-events.md) — _(no submodules)_- [permission-middleware](./src/middleware/permission-middleware/permission-middleware.md) — _(no submodules)_ - [permission-middleware](./src/middleware/permission-middleware/permission-middleware.md) — _(no submodules)_- [role-presets](./src/presets/role-presets/role-presets.md) — _(no submodules)_ - [role-presets](./src/presets/role-presets/role-presets.md) — _(no submodules)_- [schemas](./src/schemas/permissions.schemas.md) — _(no submodules)_ - [permissions.schemas](./src/schemas/permissions.schemas.md) — _(no submodules)_

Modules

Module	Description
errors/permission-error	Stable PERM.* error codes and concrete error classes
types/permissions.types	All public interfaces and type aliases
schemas/permissions.schemas	Zod validation schemas
adapters/adapter-interface	GenericPermissionAdapter interface
adapters/memory-adapter	In-memory adapter implementation
cache/permission-cache	TTL permission result cache
conditions/condition-matcher	ABAC condition evaluation
conditions/field-matcher	Dot-notation field resolution
conditions/subject-detector	Resource type detection
core/ability	Ability + AbilityBuilder
core/rule	Rule primitive
core/role-manager	Role lifecycle + inheritance
core/permission-manager	Permission CRUD + hasPermission
core/policy-engine	Policy evaluation with caching
middleware/permission-middleware	Framework-agnostic middleware
presets/role-presets	Pre-built role factories
events/permission-events	PermissionEventMap types

Quick Start

import {
  MemoryAdapter,
  PermissionManager,
  RoleManager,
  PolicyEngine,
  PermissionCache,
  buildAbility,
  createAdminRole,
} from "@suaveplan/permissions";

const adapter = new MemoryAdapter();
await adapter.createRole(createAdminRole());
await adapter.assignRole({ id: "ur1", userId: "u1", roleId: "admin", assignedAt: new Date() });

const manager = new PermissionManager(adapter);
const engine = new PolicyEngine(manager, {
  cache: new PermissionCache({ ttl: 30_000 }),
});

const result = await engine.evaluate("u1", "posts", "delete");
console.log(result.allowed); // true

const ability = buildAbility((b) => {
  b.can("read", "*");
  b.cannot("delete", "system-roles");
});
console.log(ability.can("delete", "system-roles")); // false