# @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.

<!-- begin:auto-docs -->
## Documentation tree

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

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

## Quick Start

```ts
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
```