@anievo-id/rbac-evolution 0.0.0-stage → 0.1.1

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 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
- # Temporary Holding Version
1
+ # @anievo-id/rbac-evolution
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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 };