@anievo-id/rbac-evolution 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +240 -2
- package/dist/adapter-BBs9C5pT.d.cts +130 -0
- package/dist/adapter-BBs9C5pT.d.ts +130 -0
- package/dist/chunk-JQ53Q7UP.js +734 -0
- package/dist/chunk-JQ53Q7UP.js.map +1 -0
- package/dist/index.cjs +867 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +402 -0
- package/dist/index.d.ts +402 -0
- package/dist/index.js +121 -0
- package/dist/index.js.map +1 -0
- package/dist/testing.cjs +913 -0
- package/dist/testing.cjs.map +1 -0
- package/dist/testing.d.cts +13 -0
- package/dist/testing.d.ts +13 -0
- package/dist/testing.js +178 -0
- package/dist/testing.js.map +1 -0
- package/package.json +70 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 AniEvo-ID
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,241 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @anievo-id/rbac-evolution
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Framework-agnostic RBAC engine for [rbac-evolution](https://github.com/AniEvo-ID/rbac-evolution) —
|
|
4
|
+
roles, permissions, guards, wildcards and teams. Inspired by
|
|
5
|
+
[spatie/laravel-permission](https://github.com/spatie/laravel-permission).
|
|
6
|
+
|
|
7
|
+
**Status: 🚧 early development — API may change before 1.0.**
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm i @anievo-id/rbac-evolution
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Quick start
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import { createRbac, MemoryAdapter } from '@anievo-id/rbac-evolution'
|
|
17
|
+
|
|
18
|
+
const rbac = createRbac({ adapter: new MemoryAdapter() })
|
|
19
|
+
|
|
20
|
+
// define permissions & roles
|
|
21
|
+
await rbac.createPermission('edit articles')
|
|
22
|
+
await rbac.createPermission('delete articles')
|
|
23
|
+
await rbac.createRole('writer')
|
|
24
|
+
await rbac.role('writer').givePermissionTo('edit articles')
|
|
25
|
+
|
|
26
|
+
// assign to a user (any { type, id } works)
|
|
27
|
+
const user = rbac.for({ type: 'user', id: 1 })
|
|
28
|
+
await user.assignRole('writer')
|
|
29
|
+
|
|
30
|
+
await user.hasRole('writer') // true
|
|
31
|
+
await user.hasPermissionTo('edit articles') // true
|
|
32
|
+
await user.can('delete articles') // false
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Subjects
|
|
36
|
+
|
|
37
|
+
A subject is anything that holds roles — `{ type: string, id: string | number }`.
|
|
38
|
+
Use `rbac.for(subject)` to work with it:
|
|
39
|
+
|
|
40
|
+
| Method | Description |
|
|
41
|
+
| --- | --- |
|
|
42
|
+
| `assignRole(...roles)` / `removeRole(...roles)` / `syncRoles(...roles)` | Manage roles |
|
|
43
|
+
| `hasRole(role \| roles[])` / `hasAnyRole(...)` / `hasAllRoles(...)` | Check roles |
|
|
44
|
+
| `givePermissionTo(...)` / `revokePermissionTo(...)` / `syncPermissions(...)` | Manage direct permissions |
|
|
45
|
+
| `hasPermissionTo(p)` | Check a permission (direct or via roles). Throws if `p` doesn't exist |
|
|
46
|
+
| `can(p)` / `cannot(p)` / `canAny(...)` / `canAll(...)` | Same check, never throws |
|
|
47
|
+
| `hasDirectPermission(p)` | Check direct permissions only |
|
|
48
|
+
| `hasAnyPermission(...)` / `hasAllPermissions(...)` | Data check for several permissions, never throws |
|
|
49
|
+
| `hasExactRoles(...roles)` | Has all of these roles and no others |
|
|
50
|
+
| `getRoleNames()` / `getPermissionNames()` / `getAllPermissions()` | Read access |
|
|
51
|
+
| `snapshot()` | `{ roles, permissions }` — serializable, for the client |
|
|
52
|
+
|
|
53
|
+
All methods accept names or objects, and either `fn('a', 'b')` or `fn(['a', 'b'])`.
|
|
54
|
+
|
|
55
|
+
## Roles
|
|
56
|
+
|
|
57
|
+
```ts
|
|
58
|
+
const writer = rbac.role('writer')
|
|
59
|
+
await writer.givePermissionTo('edit articles', 'delete articles')
|
|
60
|
+
await writer.revokePermissionTo('delete articles')
|
|
61
|
+
await writer.syncPermissions(['edit articles'])
|
|
62
|
+
await writer.getPermissionNames() // ['edit articles']
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Guards
|
|
66
|
+
|
|
67
|
+
Like Laravel guards — separate sets of roles/permissions (e.g. `web` and `api`):
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
await rbac.createPermission('edit articles', { guard: 'api' })
|
|
71
|
+
await rbac.for(client, { guard: 'api' }).givePermissionTo('edit articles')
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
The default guard is `web` (`createRbac({ defaultGuard: 'api' })` to change it).
|
|
75
|
+
|
|
76
|
+
## Wildcard permissions
|
|
77
|
+
|
|
78
|
+
```ts
|
|
79
|
+
const rbac = createRbac({ adapter, wildcard: true })
|
|
80
|
+
|
|
81
|
+
await rbac.createPermission('articles.*')
|
|
82
|
+
await rbac.for(user).givePermissionTo('articles.*')
|
|
83
|
+
|
|
84
|
+
await rbac.for(user).can('articles.edit') // true
|
|
85
|
+
await rbac.for(user).can('articles.edit.own') // true
|
|
86
|
+
await rbac.for(user).can('posts.edit') // false
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Supports `*`, `articles.*`, `articles.edit,delete` and shorter permissions implying deeper ones.
|
|
90
|
+
|
|
91
|
+
## Teams (multi-tenancy)
|
|
92
|
+
|
|
93
|
+
```ts
|
|
94
|
+
const rbac = createRbac({ adapter, teams: true })
|
|
95
|
+
|
|
96
|
+
await rbac.createRole('admin') // global role, usable in any team
|
|
97
|
+
await rbac.createRole('manager', { team: 42 }) // only exists in team 42
|
|
98
|
+
|
|
99
|
+
await rbac.for(user, { team: 42 }).assignRole('admin')
|
|
100
|
+
await rbac.for(user, { team: 42 }).hasRole('admin') // true
|
|
101
|
+
await rbac.for(user, { team: 7 }).hasRole('admin') // false
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
## Super-admin
|
|
105
|
+
|
|
106
|
+
Like spatie's `Gate::before`, you can let some subjects pass every check:
|
|
107
|
+
|
|
108
|
+
```ts
|
|
109
|
+
const rbac = createRbac({ adapter, superAdminRoles: ['super-admin'] })
|
|
110
|
+
|
|
111
|
+
await rbac.for(root).assignRole('super-admin')
|
|
112
|
+
await rbac.for(root).can('anything') // true, even if the permission doesn't exist
|
|
113
|
+
await rbac.for(root).hasPermissionTo('edit articles') // false: pure data check
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
For full control use a `before` hook. Return `true` to allow, `false` to deny, or
|
|
117
|
+
`undefined` to continue with the normal check. It may be async:
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
createRbac({
|
|
121
|
+
adapter,
|
|
122
|
+
superAdminRoles: ['super-admin'],
|
|
123
|
+
before: async ({ subject, permission }) => {
|
|
124
|
+
if (permission === 'delete everything') return false // nobody, not even super-admins
|
|
125
|
+
if (await isBanned(subject.subject)) return false
|
|
126
|
+
return undefined
|
|
127
|
+
},
|
|
128
|
+
})
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
`before` runs first. If it returns `undefined`, `superAdminRoles` is checked, then the normal
|
|
132
|
+
check. `subject` is the scoped `SubjectRbac` (it has `subject`, `guardName`, `teamId`, `hasRole()`...).
|
|
133
|
+
|
|
134
|
+
> As in spatie, only `can()`, `cannot()`, `canAny()` and `canAll()` use `before` and
|
|
135
|
+
> `superAdminRoles`. `hasPermissionTo()`, `hasDirectPermission()`, `hasAnyPermission()`,
|
|
136
|
+
> `hasAllPermissions()` and the role checks only look at the stored data.
|
|
137
|
+
|
|
138
|
+
## Events
|
|
139
|
+
|
|
140
|
+
```ts
|
|
141
|
+
const off = rbac.on('role.attached', async ({ subject, roles, teamId }) => {
|
|
142
|
+
await audit.log(`${subject.type}#${subject.id} got ${roles.map((r) => r.name).join(', ')}`)
|
|
143
|
+
})
|
|
144
|
+
off() // or rbac.off('role.attached', listener)
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
| Event | Fired by | Payload |
|
|
148
|
+
| --- | --- | --- |
|
|
149
|
+
| `role.attached` / `role.detached` | `assignRole`, `removeRole`, `syncRoles` | `{ subject, roles, guardName, teamId }` |
|
|
150
|
+
| `permission.attached` / `permission.detached` | `givePermissionTo`, `revokePermissionTo`, `syncPermissions` on a subject or a role | `{ target: 'subject', subject, ... }` or `{ target: 'role', role, ... }`, plus `{ permissions, guardName, teamId }` |
|
|
151
|
+
| `role.created` / `role.deleted` | `createRole` (and `findOrCreateRole`), `deleteRole` | `{ role, teamId }` |
|
|
152
|
+
| `permission.created` / `permission.deleted` | `createPermission` (and `findOrCreatePermission`), `deletePermission` | `{ permission }` |
|
|
153
|
+
|
|
154
|
+
Every payload has an `event` field, so `RbacEvent` is a discriminated union.
|
|
155
|
+
|
|
156
|
+
- Events fire only after the adapter write succeeds and the cache has been cleared.
|
|
157
|
+
- Listeners run in registration order. Async listeners are awaited one by one, and the
|
|
158
|
+
method (e.g. `assignRole`) resolves after all of them. If a listener throws, the error
|
|
159
|
+
reaches the caller, but the change is already saved.
|
|
160
|
+
- Only real changes are reported. Assigning a role the subject already has emits nothing.
|
|
161
|
+
`sync*` emits `detached` for what was removed and then `attached` for what was added.
|
|
162
|
+
- To find what changed, attach/detach do one extra adapter read, but only when a listener
|
|
163
|
+
is registered for that event.
|
|
164
|
+
- Deleting a role or permission emits only `*.deleted`, not `detached` for every subject.
|
|
165
|
+
|
|
166
|
+
## Typed names
|
|
167
|
+
|
|
168
|
+
Like spatie's enum support, you can tell the engine which permission and role names are valid:
|
|
169
|
+
|
|
170
|
+
```ts
|
|
171
|
+
type AppRbac = {
|
|
172
|
+
permissions: 'edit articles' | 'delete articles'
|
|
173
|
+
roles: 'writer' | 'admin'
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
const rbac = createRbac<AppRbac>({ adapter })
|
|
177
|
+
|
|
178
|
+
await rbac.for(user).can('edit articles') // ok
|
|
179
|
+
await rbac.for(user).can('fly') // type error
|
|
180
|
+
await rbac.for(user).assignRole('ghost') // type error
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
TS string enums work too, either as enum members or as their literal values:
|
|
184
|
+
|
|
185
|
+
```ts
|
|
186
|
+
enum Perm { Edit = 'edit articles', Delete = 'delete articles' }
|
|
187
|
+
const rbac = createRbac<{ permissions: Perm }>({ adapter }) // roles: any string
|
|
188
|
+
|
|
189
|
+
await rbac.for(user).can(Perm.Edit) // ok
|
|
190
|
+
await rbac.for(user).can('edit articles') // ok
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
- Name inputs are type-checked everywhere: `createPermission`, `findRole`, `role()`,
|
|
194
|
+
`givePermissionTo`, `can`, `hasRole`, `assignRole`, `superAdminRoles`, the query methods, and so on.
|
|
195
|
+
`Permission` and `Role` objects are always accepted.
|
|
196
|
+
- Return values (`getRoleNames()`, `snapshot()`, ...) stay `string[]`, because the database may
|
|
197
|
+
contain other names.
|
|
198
|
+
- With `wildcard: true`, add the names you check to the union too (`'articles.*' | 'articles.edit'`).
|
|
199
|
+
- With no type argument everything accepts `string`, as before. `Rbac`, `SubjectRbac` and
|
|
200
|
+
`RoleRbac` without type arguments still work, and a typed instance can be passed where `Rbac` is expected.
|
|
201
|
+
- Helper types: `RbacTypeConfig`, `PermissionName<T>`, `RoleName<T>`.
|
|
202
|
+
|
|
203
|
+
## Querying subjects
|
|
204
|
+
|
|
205
|
+
Like spatie's `User::role('writer')` and `User::permission('edit articles')` scopes, these return
|
|
206
|
+
the ids of matching subjects of a type:
|
|
207
|
+
|
|
208
|
+
```ts
|
|
209
|
+
await rbac.subjectsWithRole('user', 'writer') // [1, 4]
|
|
210
|
+
await rbac.subjectsWithRole('user', ['writer', 'editor']) // any of the roles
|
|
211
|
+
await rbac.subjectsWithPermission('user', 'edit articles') // direct or via a role
|
|
212
|
+
await rbac.subjectsWithPermission('user', 'edit articles', { team: 42, guard: 'api' })
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
- Unknown names throw `RoleDoesNotExist` / `PermissionDoesNotExist`.
|
|
216
|
+
- Wildcard patterns are not expanded. A subject is found only if it has exactly that permission,
|
|
217
|
+
directly or through a role.
|
|
218
|
+
|
|
219
|
+
On a subject, `hasExactRoles('writer', 'editor')` is `true` only if the subject has exactly
|
|
220
|
+
those roles, no more and no fewer.
|
|
221
|
+
|
|
222
|
+
## Caching
|
|
223
|
+
|
|
224
|
+
Each subject's roles & permissions are cached (in memory by default, 24h TTL) and the
|
|
225
|
+
cache is cleared automatically on every change. Plug in your own store (Redis, KV, ...):
|
|
226
|
+
|
|
227
|
+
```ts
|
|
228
|
+
createRbac({ adapter, cache: myStore, cacheTtl: 60_000 }) // implements CacheStore
|
|
229
|
+
createRbac({ adapter, cache: false }) // disable
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
## Adapters
|
|
233
|
+
|
|
234
|
+
`MemoryAdapter` is built in. Prisma, Drizzle and others are planned as separate packages.
|
|
235
|
+
To support another database, implement the `RbacAdapter` interface.
|
|
236
|
+
|
|
237
|
+
> ⚠️ Client-side checks are for UI only. Always enforce permissions on the server.
|
|
238
|
+
|
|
239
|
+
## License
|
|
240
|
+
|
|
241
|
+
MIT
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
/** Primary key type used by adapters (auto-increment number, UUID string, ObjectId string, ...). */
|
|
2
|
+
type Id = string | number;
|
|
3
|
+
/** Team identifier. `null` means "no team" (global). */
|
|
4
|
+
type TeamId = Id | null;
|
|
5
|
+
interface Permission {
|
|
6
|
+
id: Id;
|
|
7
|
+
name: string;
|
|
8
|
+
guardName: string;
|
|
9
|
+
}
|
|
10
|
+
interface Role {
|
|
11
|
+
id: Id;
|
|
12
|
+
name: string;
|
|
13
|
+
guardName: string;
|
|
14
|
+
/** `null` for global roles. Only used when `teams` is enabled. */
|
|
15
|
+
teamId: TeamId;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Anything that can hold roles and permissions — usually a user,
|
|
19
|
+
* but can be any model (e.g. an API client, a service account).
|
|
20
|
+
* Equivalent to Laravel's `model_type` + `model_id`.
|
|
21
|
+
*/
|
|
22
|
+
interface Subject {
|
|
23
|
+
type: string;
|
|
24
|
+
id: Id;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* A permission can be referenced by its name or by the permission object itself.
|
|
28
|
+
* `P` narrows the accepted names (see {@link RbacTypeConfig}); defaults to any string.
|
|
29
|
+
*/
|
|
30
|
+
type PermissionInput<P extends string = string> = P | Permission;
|
|
31
|
+
/**
|
|
32
|
+
* A role can be referenced by its name or by the role object itself.
|
|
33
|
+
* `R` narrows the accepted names (see {@link RbacTypeConfig}); defaults to any string.
|
|
34
|
+
*/
|
|
35
|
+
type RoleInput<R extends string = string> = R | Role;
|
|
36
|
+
/**
|
|
37
|
+
* Type-level configuration of an `Rbac` instance — the equivalent of spatie's enums.
|
|
38
|
+
*
|
|
39
|
+
* ```ts
|
|
40
|
+
* const rbac = createRbac<{ permissions: 'edit articles' | 'delete articles'; roles: 'writer' }>({ adapter })
|
|
41
|
+
* await rbac.for(user).can('edit articles') // ok
|
|
42
|
+
* await rbac.for(user).can('fly') // type error
|
|
43
|
+
* ```
|
|
44
|
+
*
|
|
45
|
+
* Both keys are optional; a missing key accepts any string. TS string enums work too.
|
|
46
|
+
*/
|
|
47
|
+
interface RbacTypeConfig {
|
|
48
|
+
permissions?: string;
|
|
49
|
+
roles?: string;
|
|
50
|
+
}
|
|
51
|
+
/** Default type configuration: any string is a valid permission / role name. */
|
|
52
|
+
interface DefaultRbacTypes {
|
|
53
|
+
permissions: string;
|
|
54
|
+
roles: string;
|
|
55
|
+
}
|
|
56
|
+
/** Permission names accepted by an `Rbac<T>` (string enums also accept their literal values). */
|
|
57
|
+
type PermissionName<T extends RbacTypeConfig = DefaultRbacTypes> = T extends {
|
|
58
|
+
permissions: infer P extends string;
|
|
59
|
+
} ? P | `${P}` : string;
|
|
60
|
+
/** Role names accepted by an `Rbac<T>` (string enums also accept their literal values). */
|
|
61
|
+
type RoleName<T extends RbacTypeConfig = DefaultRbacTypes> = T extends {
|
|
62
|
+
roles: infer R extends string;
|
|
63
|
+
} ? R | `${R}` : string;
|
|
64
|
+
/** Lets methods accept both `fn('a', 'b')` and `fn(['a', 'b'])`. */
|
|
65
|
+
type Many<T> = T | readonly T[];
|
|
66
|
+
/** Serializable summary of a subject's access — handy for sending to the client (React, Vue, ...). */
|
|
67
|
+
interface RbacSnapshot {
|
|
68
|
+
roles: string[];
|
|
69
|
+
permissions: string[];
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
interface FindPermissionsQuery {
|
|
73
|
+
ids?: readonly Id[];
|
|
74
|
+
names?: readonly string[];
|
|
75
|
+
guardName?: string;
|
|
76
|
+
}
|
|
77
|
+
interface FindRolesQuery {
|
|
78
|
+
ids?: readonly Id[];
|
|
79
|
+
names?: readonly string[];
|
|
80
|
+
guardName?: string;
|
|
81
|
+
/** Match roles whose `teamId` is one of these values (`null` = global roles). */
|
|
82
|
+
teamIds?: readonly TeamId[];
|
|
83
|
+
}
|
|
84
|
+
interface RolePermissionLink {
|
|
85
|
+
roleId: Id;
|
|
86
|
+
permissionId: Id;
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* Storage layer. Implement this to plug rbac-evolution into any database / ORM
|
|
90
|
+
* (Prisma, Drizzle, TypeORM, Mongoose, ...).
|
|
91
|
+
*
|
|
92
|
+
* Conceptually it maps to the same tables as spatie/laravel-permission:
|
|
93
|
+
* `permissions`, `roles`, `role_has_permissions`, `model_has_roles`, `model_has_permissions`.
|
|
94
|
+
*
|
|
95
|
+
* Rules for implementers:
|
|
96
|
+
* - All `attach*` methods must be idempotent (attaching an existing link is a no-op).
|
|
97
|
+
* - `detach*` methods with `undefined` ids remove every link for that owner (and team).
|
|
98
|
+
* - `deletePermission` / `deleteRole` must also remove their links.
|
|
99
|
+
* - Uniqueness of names is checked by the engine; adapters may additionally enforce it.
|
|
100
|
+
*/
|
|
101
|
+
interface RbacAdapter {
|
|
102
|
+
createPermission(data: {
|
|
103
|
+
name: string;
|
|
104
|
+
guardName: string;
|
|
105
|
+
}): Promise<Permission>;
|
|
106
|
+
findPermissions(query?: FindPermissionsQuery): Promise<Permission[]>;
|
|
107
|
+
deletePermission(id: Id): Promise<void>;
|
|
108
|
+
createRole(data: {
|
|
109
|
+
name: string;
|
|
110
|
+
guardName: string;
|
|
111
|
+
teamId: TeamId;
|
|
112
|
+
}): Promise<Role>;
|
|
113
|
+
findRoles(query?: FindRolesQuery): Promise<Role[]>;
|
|
114
|
+
deleteRole(id: Id): Promise<void>;
|
|
115
|
+
getRolePermissionLinks(roleIds: readonly Id[]): Promise<RolePermissionLink[]>;
|
|
116
|
+
attachRolePermissions(roleId: Id, permissionIds: readonly Id[]): Promise<void>;
|
|
117
|
+
detachRolePermissions(roleId: Id, permissionIds?: readonly Id[]): Promise<void>;
|
|
118
|
+
getSubjectRoleIds(subject: Subject, teamId: TeamId): Promise<Id[]>;
|
|
119
|
+
attachSubjectRoles(subject: Subject, roleIds: readonly Id[], teamId: TeamId): Promise<void>;
|
|
120
|
+
detachSubjectRoles(subject: Subject, roleIds: readonly Id[] | undefined, teamId: TeamId): Promise<void>;
|
|
121
|
+
getSubjectPermissionIds(subject: Subject, teamId: TeamId): Promise<Id[]>;
|
|
122
|
+
attachSubjectPermissions(subject: Subject, permissionIds: readonly Id[], teamId: TeamId): Promise<void>;
|
|
123
|
+
detachSubjectPermissions(subject: Subject, permissionIds: readonly Id[] | undefined, teamId: TeamId): Promise<void>;
|
|
124
|
+
/** Ids of subjects of `subjectType` that have ANY of the given roles in the given team. Unique. */
|
|
125
|
+
getSubjectIdsWithRoles(subjectType: string, roleIds: readonly Id[], teamId: TeamId): Promise<Id[]>;
|
|
126
|
+
/** Ids of subjects of `subjectType` that have ANY of the given DIRECT permissions in the given team. Unique. */
|
|
127
|
+
getSubjectIdsWithPermissions(subjectType: string, permissionIds: readonly Id[], teamId: TeamId): Promise<Id[]>;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
export type { DefaultRbacTypes as D, FindPermissionsQuery as F, Id as I, Many as M, Permission as P, Role as R, Subject as S, TeamId as T, RbacTypeConfig as a, RbacAdapter as b, RoleName as c, RoleInput as d, PermissionInput as e, PermissionName as f, RbacSnapshot as g, FindRolesQuery as h, RolePermissionLink as i };
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
/** Primary key type used by adapters (auto-increment number, UUID string, ObjectId string, ...). */
|
|
2
|
+
type Id = string | number;
|
|
3
|
+
/** Team identifier. `null` means "no team" (global). */
|
|
4
|
+
type TeamId = Id | null;
|
|
5
|
+
interface Permission {
|
|
6
|
+
id: Id;
|
|
7
|
+
name: string;
|
|
8
|
+
guardName: string;
|
|
9
|
+
}
|
|
10
|
+
interface Role {
|
|
11
|
+
id: Id;
|
|
12
|
+
name: string;
|
|
13
|
+
guardName: string;
|
|
14
|
+
/** `null` for global roles. Only used when `teams` is enabled. */
|
|
15
|
+
teamId: TeamId;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Anything that can hold roles and permissions — usually a user,
|
|
19
|
+
* but can be any model (e.g. an API client, a service account).
|
|
20
|
+
* Equivalent to Laravel's `model_type` + `model_id`.
|
|
21
|
+
*/
|
|
22
|
+
interface Subject {
|
|
23
|
+
type: string;
|
|
24
|
+
id: Id;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* A permission can be referenced by its name or by the permission object itself.
|
|
28
|
+
* `P` narrows the accepted names (see {@link RbacTypeConfig}); defaults to any string.
|
|
29
|
+
*/
|
|
30
|
+
type PermissionInput<P extends string = string> = P | Permission;
|
|
31
|
+
/**
|
|
32
|
+
* A role can be referenced by its name or by the role object itself.
|
|
33
|
+
* `R` narrows the accepted names (see {@link RbacTypeConfig}); defaults to any string.
|
|
34
|
+
*/
|
|
35
|
+
type RoleInput<R extends string = string> = R | Role;
|
|
36
|
+
/**
|
|
37
|
+
* Type-level configuration of an `Rbac` instance — the equivalent of spatie's enums.
|
|
38
|
+
*
|
|
39
|
+
* ```ts
|
|
40
|
+
* const rbac = createRbac<{ permissions: 'edit articles' | 'delete articles'; roles: 'writer' }>({ adapter })
|
|
41
|
+
* await rbac.for(user).can('edit articles') // ok
|
|
42
|
+
* await rbac.for(user).can('fly') // type error
|
|
43
|
+
* ```
|
|
44
|
+
*
|
|
45
|
+
* Both keys are optional; a missing key accepts any string. TS string enums work too.
|
|
46
|
+
*/
|
|
47
|
+
interface RbacTypeConfig {
|
|
48
|
+
permissions?: string;
|
|
49
|
+
roles?: string;
|
|
50
|
+
}
|
|
51
|
+
/** Default type configuration: any string is a valid permission / role name. */
|
|
52
|
+
interface DefaultRbacTypes {
|
|
53
|
+
permissions: string;
|
|
54
|
+
roles: string;
|
|
55
|
+
}
|
|
56
|
+
/** Permission names accepted by an `Rbac<T>` (string enums also accept their literal values). */
|
|
57
|
+
type PermissionName<T extends RbacTypeConfig = DefaultRbacTypes> = T extends {
|
|
58
|
+
permissions: infer P extends string;
|
|
59
|
+
} ? P | `${P}` : string;
|
|
60
|
+
/** Role names accepted by an `Rbac<T>` (string enums also accept their literal values). */
|
|
61
|
+
type RoleName<T extends RbacTypeConfig = DefaultRbacTypes> = T extends {
|
|
62
|
+
roles: infer R extends string;
|
|
63
|
+
} ? R | `${R}` : string;
|
|
64
|
+
/** Lets methods accept both `fn('a', 'b')` and `fn(['a', 'b'])`. */
|
|
65
|
+
type Many<T> = T | readonly T[];
|
|
66
|
+
/** Serializable summary of a subject's access — handy for sending to the client (React, Vue, ...). */
|
|
67
|
+
interface RbacSnapshot {
|
|
68
|
+
roles: string[];
|
|
69
|
+
permissions: string[];
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
interface FindPermissionsQuery {
|
|
73
|
+
ids?: readonly Id[];
|
|
74
|
+
names?: readonly string[];
|
|
75
|
+
guardName?: string;
|
|
76
|
+
}
|
|
77
|
+
interface FindRolesQuery {
|
|
78
|
+
ids?: readonly Id[];
|
|
79
|
+
names?: readonly string[];
|
|
80
|
+
guardName?: string;
|
|
81
|
+
/** Match roles whose `teamId` is one of these values (`null` = global roles). */
|
|
82
|
+
teamIds?: readonly TeamId[];
|
|
83
|
+
}
|
|
84
|
+
interface RolePermissionLink {
|
|
85
|
+
roleId: Id;
|
|
86
|
+
permissionId: Id;
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* Storage layer. Implement this to plug rbac-evolution into any database / ORM
|
|
90
|
+
* (Prisma, Drizzle, TypeORM, Mongoose, ...).
|
|
91
|
+
*
|
|
92
|
+
* Conceptually it maps to the same tables as spatie/laravel-permission:
|
|
93
|
+
* `permissions`, `roles`, `role_has_permissions`, `model_has_roles`, `model_has_permissions`.
|
|
94
|
+
*
|
|
95
|
+
* Rules for implementers:
|
|
96
|
+
* - All `attach*` methods must be idempotent (attaching an existing link is a no-op).
|
|
97
|
+
* - `detach*` methods with `undefined` ids remove every link for that owner (and team).
|
|
98
|
+
* - `deletePermission` / `deleteRole` must also remove their links.
|
|
99
|
+
* - Uniqueness of names is checked by the engine; adapters may additionally enforce it.
|
|
100
|
+
*/
|
|
101
|
+
interface RbacAdapter {
|
|
102
|
+
createPermission(data: {
|
|
103
|
+
name: string;
|
|
104
|
+
guardName: string;
|
|
105
|
+
}): Promise<Permission>;
|
|
106
|
+
findPermissions(query?: FindPermissionsQuery): Promise<Permission[]>;
|
|
107
|
+
deletePermission(id: Id): Promise<void>;
|
|
108
|
+
createRole(data: {
|
|
109
|
+
name: string;
|
|
110
|
+
guardName: string;
|
|
111
|
+
teamId: TeamId;
|
|
112
|
+
}): Promise<Role>;
|
|
113
|
+
findRoles(query?: FindRolesQuery): Promise<Role[]>;
|
|
114
|
+
deleteRole(id: Id): Promise<void>;
|
|
115
|
+
getRolePermissionLinks(roleIds: readonly Id[]): Promise<RolePermissionLink[]>;
|
|
116
|
+
attachRolePermissions(roleId: Id, permissionIds: readonly Id[]): Promise<void>;
|
|
117
|
+
detachRolePermissions(roleId: Id, permissionIds?: readonly Id[]): Promise<void>;
|
|
118
|
+
getSubjectRoleIds(subject: Subject, teamId: TeamId): Promise<Id[]>;
|
|
119
|
+
attachSubjectRoles(subject: Subject, roleIds: readonly Id[], teamId: TeamId): Promise<void>;
|
|
120
|
+
detachSubjectRoles(subject: Subject, roleIds: readonly Id[] | undefined, teamId: TeamId): Promise<void>;
|
|
121
|
+
getSubjectPermissionIds(subject: Subject, teamId: TeamId): Promise<Id[]>;
|
|
122
|
+
attachSubjectPermissions(subject: Subject, permissionIds: readonly Id[], teamId: TeamId): Promise<void>;
|
|
123
|
+
detachSubjectPermissions(subject: Subject, permissionIds: readonly Id[] | undefined, teamId: TeamId): Promise<void>;
|
|
124
|
+
/** Ids of subjects of `subjectType` that have ANY of the given roles in the given team. Unique. */
|
|
125
|
+
getSubjectIdsWithRoles(subjectType: string, roleIds: readonly Id[], teamId: TeamId): Promise<Id[]>;
|
|
126
|
+
/** Ids of subjects of `subjectType` that have ANY of the given DIRECT permissions in the given team. Unique. */
|
|
127
|
+
getSubjectIdsWithPermissions(subjectType: string, permissionIds: readonly Id[], teamId: TeamId): Promise<Id[]>;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
export type { DefaultRbacTypes as D, FindPermissionsQuery as F, Id as I, Many as M, Permission as P, Role as R, Subject as S, TeamId as T, RbacTypeConfig as a, RbacAdapter as b, RoleName as c, RoleInput as d, PermissionInput as e, PermissionName as f, RbacSnapshot as g, FindRolesQuery as h, RolePermissionLink as i };
|