98 lines
21 KiB
Markdown
98 lines
21 KiB
Markdown
# @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
|
|
```
|