@zealamic/payload-auth-rbac-plugin 1.0.0-beta.10 → 1.0.0-beta.11

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.
Files changed (5) hide show
  1. package/README.md +27 -31
  2. package/docs/COLLECTIONS.md +105 -91
  3. package/docs/TRANSLATIONS.md +3 -3
  4. package/docs/UTILS.md +25 -20
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -10,13 +10,13 @@ Permissions live in the database (feature + action), are assigned to roles, and
10
10
 
11
11
  ## Documentation
12
12
 
13
- | Guide | Read when you need to… |
14
- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
15
- | **[COLLECTIONS](./docs/COLLECTIONS.md)** | Understand plugin collections, users augmentation, `dataScope`, permission matrix, and **customize** fields/access/admin |
16
- | **[UTILS](./docs/UTILS.md)** | Wire **access helpers** on your app collections (`getPermissionAccess`, data-scope filters, examples) |
17
- | **[TRANSLATIONS](./docs/TRANSLATIONS.md)** | Localize Admin labels, select options, and permission-matrix UI (`en`, `vi`, …) |
13
+ | Guide | Read when you need to… |
14
+ | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
15
+ | **[COLLECTIONS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/COLLECTIONS.md)** | Understand plugin collections, users augmentation, `dataScope`, permission matrix, and **customize** fields/access/admin |
16
+ | **[UTILS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/UTILS.md)** | Wire **access helpers** on your app collections (`getPermissionAccess`, data-scope filters, examples) |
17
+ | **[TRANSLATIONS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/TRANSLATIONS.md)** | Localize Admin labels, select options, and permission-matrix UI (`en`, `vi`, …) |
18
18
 
19
- **Typical flow:** install → register plugin → seed RBAC data ([COLLECTIONS](./docs/COLLECTIONS.md)) → protect app collections ([UTILS](./docs/UTILS.md)) → translate Admin UI ([TRANSLATIONS](./docs/TRANSLATIONS.md)).
19
+ **Typical flow:** install → register plugin → seed RBAC data ([COLLECTIONS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/COLLECTIONS.md)) → protect app collections ([UTILS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/UTILS.md)) → translate Admin UI ([TRANSLATIONS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/TRANSLATIONS.md)).
20
20
 
21
21
  Demo: `dev/rbac.ts`, `dev/collections/posts.ts`.
22
22
 
@@ -24,13 +24,13 @@ Demo: `dev/rbac.ts`, `dev/collections/posts.ts`.
24
24
 
25
25
  ## Key features
26
26
 
27
- - **Five RBAC collections** — features, actions, permissions, roles, join table ([details](./docs/COLLECTIONS.md))
27
+ - **Five RBAC collections** — features, actions, permissions, roles, join table ([details](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/COLLECTIONS.md))
28
28
  - **Multi-role users** — union of enabled grants across assigned roles
29
- - **Granular permissions** — any `featureCode` + `actionCode` pair ([helpers](./docs/UTILS.md))
30
- - **Data scope** — per-role `own` / `hierarchy` / `all` for row-level filtering (`[dataScope` vs `isSuperAdmin](./docs/COLLECTIONS.md#what-is-datascope)`)
29
+ - **Granular permissions** — any `featureCode` + `actionCode` pair ([helpers](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/UTILS.md))
30
+ - **Data scope** — per-role `own` / `hierarchy` / `all` for row-level filtering (`[dataScope` vs `isSuperAdmin](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/COLLECTIONS.md#what-is-datascope)`)
31
31
  - **Permission matrix** — role edit UI; syncs to `roles-permissions` on save
32
32
  - **TypeScript** — typed plugin options and exports (`/types`)
33
- - **i18n** — plugin-owned translations merged into Payload i18n ([guide](./docs/TRANSLATIONS.md))
33
+ - **i18n** — plugin-owned translations merged into Payload i18n ([guide](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/TRANSLATIONS.md))
34
34
 
35
35
  ---
36
36
 
@@ -66,17 +66,15 @@ export default buildConfig({
66
66
  1. **permission-features** — e.g. `posts`, `users` (`code` = `featureCode` in access helpers)
67
67
  2. **permission-actions** — e.g. `create`, `read`, `update`, `delete`
68
68
  3. **permissions** — one row per feature + action pair
69
- 4. **roles** — set `[dataScope](./docs/COLLECTIONS.md#what-is-datascope)`; configure matrix on update screen → Save
70
- 5. **users** — assign roles; bootstrap `[isSuperAdmin](./docs/COLLECTIONS.md#bootstrap-super-admin)` via seed/API
69
+ 4. **roles** — set `[dataScope](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/COLLECTIONS.md#what-is-datascope)`; configure matrix on update screen → Save
70
+ 5. **users** — assign roles; bootstrap `[isSuperAdmin](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/COLLECTIONS.md#bootstrap-super-admin)` via seed/API
71
71
 
72
- → Full collection reference: **[COLLECTIONS](./docs/COLLECTIONS.md)**
72
+ → Full collection reference: **[COLLECTIONS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/COLLECTIONS.md)**
73
73
 
74
74
  ### 3. Protect app collections
75
75
 
76
76
  ```ts
77
- import {
78
- getPermissionAccess,
79
- } from "@zealamic/payload-auth-rbac-plugin";
77
+ import { getPermissionAccess } from "@zealamic/payload-auth-rbac-plugin";
80
78
 
81
79
  export const Posts: CollectionConfig = {
82
80
  slug: "posts",
@@ -121,18 +119,18 @@ export const Posts: CollectionConfig = {
121
119
 
122
120
  **Access order:** anonymous → deny · super admin → allow · else → matrix permission (+ data scope when using scope helpers).
123
121
 
124
- → All helpers with examples: **[UTILS](./docs/UTILS.md)**
122
+ → All helpers with examples: **[UTILS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/UTILS.md)**
125
123
 
126
124
  ---
127
125
 
128
126
  ## Plugin options
129
127
 
130
- | Option | Default | Description |
131
- | --------------------------- | ------- | ------------------------------------------------------------------------------------------- |
132
- | `disabled` | `false` | Skip runtime wiring; schema still registers |
133
- | `autoModifyUsersCollection` | `true` | Add RBAC fields + access on users collection |
134
- | `translations` | — | Admin / matrix i18n → **[TRANSLATIONS](./docs/TRANSLATIONS.md)** |
135
- | `collections` | — | Per-collection overrides → **[COLLECTIONS](./docs/COLLECTIONS.md#customizing-collections)** |
128
+ | Option | Default | Description |
129
+ | --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
130
+ | `disabled` | `false` | Skip runtime wiring; schema still registers |
131
+ | `autoModifyUsersCollection` | `true` | Add RBAC fields + access on users collection |
132
+ | `translations` | — | Admin / matrix i18n → **[TRANSLATIONS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/TRANSLATIONS.md)** |
133
+ | `collections` | — | Per-collection overrides → **[COLLECTIONS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/COLLECTIONS.md#customizing-collections)** |
136
134
 
137
135
  Types: `@zealamic/payload-auth-rbac-plugin/types`
138
136
 
@@ -140,14 +138,14 @@ Types: `@zealamic/payload-auth-rbac-plugin/types`
140
138
 
141
139
  ## Exported helpers (summary)
142
140
 
143
- Full reference: **[UTILS](./docs/UTILS.md)**
141
+ Full reference: **[UTILS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/UTILS.md)**
144
142
 
145
- | Function | Purpose |
146
- | ----------------------------------------------------- | ----------------------------------------------- |
143
+ | Function | Purpose |
144
+ | ----------------------------------------------------- | ------------------------------------------------------ |
147
145
  | `getPermissionAccess` | Unified helper: permission / read scope / modify scope |
148
- | `getSuperAdminAccess` | Super admin only (RBAC collections default) |
149
- | `canAccessDocumentByDataScope` | Single-document scope check |
150
- | `resolveEffectiveDataScope` / `getDataScopeReadWhere` | Scope resolution & query filters |
146
+ | `getSuperAdminAccess` | Super admin only (RBAC collections default) |
147
+ | `canAccessDocumentByDataScope` | Single-document scope check |
148
+ | `resolveEffectiveDataScope` / `getDataScopeReadWhere` | Scope resolution & query filters |
151
149
 
152
150
  Constants: `CONSTANTS.ROLE.DATA_SCOPE`, etc.
153
151
 
@@ -171,5 +169,3 @@ MIT
171
169
  ---
172
170
 
173
171
  > _If this plugin helps your team ship safer access control with less friction, thank you for giving it a place in your stack._
174
-
175
-
package/docs/COLLECTIONS.md CHANGED
@@ -13,14 +13,14 @@ permission-features ──┐
13
13
  permission-actions ──┼──► permissions ◄── roles-permissions ──► roles ◄── users.roles
14
14
  ```
15
15
 
16
- | Config key (camelCase) | Slug (API) | Purpose |
17
- |------------------------|------------|---------|
18
- | `permissionActions` | `permission-actions` | Action verbs (`create`, `read`, …) |
19
- | `permissionFeatures` | `permission-features` | Resource areas (`users`, `posts`, …) |
20
- | `permissions` | `permissions` | Feature + action pairs (enforceable units) |
21
- | `roles` | `roles` | Role definitions + permission matrix UI |
22
- | `rolesPermissions` | `roles-permissions` | Join table: role ↔ permission ↔ enabled |
23
- | — | `users` (app) | Auth collection — plugin adds fields + access |
16
+ | Config key (camelCase) | Slug (API) | Purpose |
17
+ | ---------------------- | --------------------- | --------------------------------------------- |
18
+ | `permissionActions` | `permission-actions` | Action verbs (`create`, `read`, …) |
19
+ | `permissionFeatures` | `permission-features` | Resource areas (`users`, `posts`, …) |
20
+ | `permissions` | `permissions` | Feature + action pairs (enforceable units) |
21
+ | `roles` | `roles` | Role definitions + permission matrix UI |
22
+ | `rolesPermissions` | `roles-permissions` | Join table: role ↔ permission ↔ enabled |
23
+ | — | `users` (app) | Auth collection — plugin adds fields + access |
24
24
 
25
25
  **Defaults:** only **super admins** can access the five RBAC collections. `roles-permissions` is **hidden** in Admin.
26
26
 
@@ -30,66 +30,66 @@ permission-actions ──┼──► permissions ◄── roles-permissions
30
30
 
31
31
  ### `permission-actions`
32
32
 
33
- | Field | Description |
34
- |-------|-------------|
35
- | `code` | Unique code — must match `actionCode` in `getPermissionAccess` |
36
- | `type` | `main` (matrix column) or `sub` (sub-action row) |
37
- | `sortOrder` | Display order |
38
- | `status` | `active` / `inactive` |
33
+ | Field | Description |
34
+ | ----------- | -------------------------------------------------------------- |
35
+ | `code` | Unique code — must match `actionCode` in `getPermissionAccess` |
36
+ | `type` | `main` (matrix column) or `sub` (sub-action row) |
37
+ | `sortOrder` | Display order |
38
+ | `status` | `active` / `inactive` |
39
39
 
40
40
  ### `permission-features`
41
41
 
42
- | Field | Description |
43
- |-------|-------------|
44
- | `code` | Unique code — must match `featureCode` in access helpers |
45
- | `sortOrder` | Display order |
46
- | `status` | `active` / `inactive` |
42
+ | Field | Description |
43
+ | ----------- | -------------------------------------------------------- |
44
+ | `code` | Unique code — must match `featureCode` in access helpers |
45
+ | `sortOrder` | Display order |
46
+ | `status` | `active` / `inactive` |
47
47
 
48
48
  ### `permissions`
49
49
 
50
- | Field | Description |
51
- |-------|-------------|
52
- | `name` | Human-readable label |
53
- | `permissionFeature` | → `permission-features` |
54
- | `permissionAction` | → `permission-actions` |
55
- | `sortOrder` | Optional ordering |
56
- | `status` | Only `active` permissions are enforced |
50
+ | Field | Description |
51
+ | ------------------- | -------------------------------------- |
52
+ | `name` | Human-readable label |
53
+ | `permissionFeature` | → `permission-features` |
54
+ | `permissionAction` | → `permission-actions` |
55
+ | `sortOrder` | Optional ordering |
56
+ | `status` | Only `active` permissions are enforced |
57
57
 
58
58
  ### `roles`
59
59
 
60
- | Field | Description |
61
- |-------|-------------|
62
- | `code` | Unique machine identifier |
63
- | `name` | Display name |
64
- | `description` | Optional |
65
- | `status` | `active` / `inactive` |
66
- | `dataScope` | `own` / `hierarchy` / `all` — limits **which documents** a user can read/update/delete (see below) |
67
- | `permissionMatrixDraft` | JSON field + custom matrix UI (update screen only) |
60
+ | Field | Description |
61
+ | ----------------------- | -------------------------------------------------------------------------------------------------- |
62
+ | `code` | Unique machine identifier |
63
+ | `name` | Display name |
64
+ | `description` | Optional |
65
+ | `status` | `active` / `inactive` |
66
+ | `dataScope` | `own` / `hierarchy` / `all` — limits **which documents** a user can read/update/delete (see below) |
67
+ | `permissionMatrixDraft` | JSON field + custom matrix UI (update screen only) |
68
68
 
69
69
  #### What is `dataScope`?
70
70
 
71
- `dataScope` answers: *“After the user passes the permission check, which rows/documents can they see or change?”*
71
+ `dataScope` answers: _“After the user passes the permission check, which rows/documents can they see or change?”_
72
72
 
73
73
  It works **together with** the permission matrix (`roles-permissions`). The matrix controls **whether** an action is allowed; `dataScope` controls **how far** that action reaches.
74
74
 
75
- | Value | Who can access documents |
76
- |-------|--------------------------|
77
- | `own` | Only records the user created (`createdBy` = current user) |
78
- | `hierarchy` | Records created by the user **or** their subordinates in the user tree (`users.parent` / `parentPath`) |
79
- | `all` | Any record **within collections that use data-scope helpers** — still requires an enabled permission in the matrix (see note below) |
75
+ | Value | Who can access documents |
76
+ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
77
+ | `own` | Only records the user created (`createdBy` = current user) |
78
+ | `hierarchy` | Records created by the user **or** their subordinates in the user tree (`users.parent` / `parentPath`) |
79
+ | `all` | Any record **within collections that use data-scope helpers** — still requires an enabled permission in the matrix (see note below) |
80
80
 
81
81
  > **`all` vs `isSuperAdmin` — not the same thing**
82
82
  >
83
- > | | `dataScope: all` (on a role) | `isSuperAdmin: true` (on a user) |
84
- > |---|---|---|
85
- > | **What it controls** | Row-level filter only — “see all documents in this feature” | Full bypass of RBAC permission + data-scope checks |
86
- > | **Still needs matrix permission?** | **Yes** — user must have the feature/action enabled on a role | **No** — skips `roles-permissions` entirely |
87
- > | **Typical use** | Operational roles: “read/update all **posts**”, “read all **orders**” | Break-glass / platform admins: manage roles, permissions, system config |
88
- > | **Privilege level** | Lower than super admin | Highest |
83
+ > | | `dataScope: all` (on a role) | `isSuperAdmin: true` (on a user) |
84
+ > | ---------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------- |
85
+ > | **What it controls** | Row-level filter only — “see all documents in this feature” | Full bypass of RBAC permission + data-scope checks |
86
+ > | **Still needs matrix permission?** | **Yes** — user must have the feature/action enabled on a role | **No** — skips `roles-permissions` entirely |
87
+ > | **Typical use** | Operational roles: “read/update all **posts**”, “read all **orders**” | Break-glass / platform admins: manage roles, permissions, system config |
88
+ > | **Privilege level** | Lower than super admin | Highest |
89
89
  >
90
90
  > **Recommended split for developers:**
91
91
  >
92
- > - Use **`dataScope: all`** on **business roles** when someone should access all records of a *specific feature* (e.g. all `posts`), but only for actions you grant in the matrix.
92
+ > - Use **`dataScope: all`** on **business roles** when someone should access all records of a _specific feature_ (e.g. all `posts`), but only for actions you grant in the matrix.
93
93
  > - Reserve **`isSuperAdmin`** for a small set of accounts that manage **system-wide RBAC config**: `roles`, `permissions`, `permission-features`, `permission-actions`, and other global settings. Plugin RBAC collections default to `getSuperAdminAccess` for this reason.
94
94
  > - Do **not** treat `all` as a substitute for super admin. A role with `all` on `posts` can read every post **only if** it has `posts` + `read` in the matrix — it cannot manage roles or permissions unless you explicitly grant those features too.
95
95
  >
@@ -120,15 +120,15 @@ read: getPermissionAndDataScopeReadAccess({
120
120
  }),
121
121
  ```
122
122
 
123
- **Users collection:** the plugin uses `createdByField: "id"` (each user document is “owned” by itself) and adds `parent` / `parentPath` for hierarchy. See [UTILS](./UTILS.md) for full helper reference.
123
+ **Users collection:** the plugin uses `createdByField: "id"` (each user document is “owned” by itself) and adds `parent` / `parentPath` for hierarchy. See [UTILS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/UTILS.md) for full helper reference.
124
124
 
125
125
  **Super admin (`isSuperAdmin`):** bypasses permission checks **and** data scope on every helper. Use sparingly for platform administrators — not for everyday business roles. Set via seed/Local API only (`isSuperAdmin` is read-only in Admin).
126
126
 
127
127
  **How the permission matrix works:**
128
128
 
129
- 1. Admin toggles checkboxes → updates `permissionMatrixDraft` on the form
130
- 2. **Save role** → `afterChange` hook syncs to `roles-permissions`
131
- 3. Runtime RBAC reads **`roles-permissions`**, not the JSON draft
129
+ 1. Admin toggles checkboxes → updates `permissionMatrixDraft` on the form
130
+ 2. **Save role** → `afterChange` hook syncs to `roles-permissions`
131
+ 3. Runtime RBAC reads **`roles-permissions`**, not the JSON draft
132
132
 
133
133
  **Field name vs translation key:** the schema field is `permissionMatrixDraft`; the translation label key is `permissionMatrix`:
134
134
 
@@ -148,11 +148,11 @@ translations: {
148
148
 
149
149
  ### `roles-permissions`
150
150
 
151
- | Field | Description |
152
- |-------|-------------|
153
- | `role` | → `roles` |
154
- | `permission` | → `permissions` |
155
- | `enabled` | Grant on/off (default `true`) |
151
+ | Field | Description |
152
+ | ------------ | ----------------------------- |
153
+ | `role` | → `roles` |
154
+ | `permission` | → `permissions` |
155
+ | `enabled` | Grant on/off (default `true`) |
156
156
 
157
157
  Managed via the matrix on the role edit screen — you normally do not open this collection in Admin.
158
158
 
@@ -166,25 +166,25 @@ Toggle with `autoModifyUsersCollection` (default: `true`).
166
166
 
167
167
  ### Fields the plugin adds
168
168
 
169
- | Field | Description |
170
- |-------|-------------|
171
- | `isSuperAdmin` | Bypasses all checks; **read-only** in Admin |
172
- | `roles` | hasMany relationship → `roles` |
173
- | `parent` | Relationship to parent user (for `hierarchy` scope) |
174
- | `parentPath` | Hidden, auto-maintained — used for hierarchy lookups |
169
+ | Field | Description |
170
+ | -------------- | ---------------------------------------------------- |
171
+ | `isSuperAdmin` | Bypasses all checks; **read-only** in Admin |
172
+ | `roles` | hasMany relationship → `roles` |
173
+ | `parent` | Relationship to parent user (for `hierarchy` scope) |
174
+ | `parentPath` | Hidden, auto-maintained — used for hierarchy lookups |
175
175
 
176
176
  ### Default access on users
177
177
 
178
178
  `featureCode` = users collection slug (e.g. `"users"`).
179
179
 
180
- | Operation | `actionCode` |
181
- |-----------|--------------|
182
- | `create` | `create` |
183
- | `read` | `read` (+ data scope) |
184
- | `update` | `update` (+ data scope) |
185
- | `delete` | `delete` (+ data scope) |
186
- | `readVersions` | `readVersions` |
187
- | `unlock` | `unlock` |
180
+ | Operation | `actionCode` |
181
+ | -------------- | ----------------------- |
182
+ | `create` | `create` |
183
+ | `read` | `read` (+ data scope) |
184
+ | `update` | `update` (+ data scope) |
185
+ | `delete` | `delete` (+ data scope) |
186
+ | `readVersions` | `readVersions` |
187
+ | `unlock` | `unlock` |
188
188
 
189
189
  Seed a `permission-features` record with `code` equal to the users slug, plus matching actions and permissions.
190
190
 
@@ -220,11 +220,21 @@ export default buildConfig({
220
220
  payloadAuthRbacPlugin({
221
221
  autoModifyUsersCollection: true,
222
222
  collections: {
223
- permissionActions: { /* ... */ },
224
- permissionFeatures: { /* ... */ },
225
- permissions: { /* ... */ },
226
- roles: { /* ... */ },
227
- rolesPermissions: { /* ... */ },
223
+ permissionActions: {
224
+ /* ... */
225
+ },
226
+ permissionFeatures: {
227
+ /* ... */
228
+ },
229
+ permissions: {
230
+ /* ... */
231
+ },
232
+ roles: {
233
+ /* ... */
234
+ },
235
+ rolesPermissions: {
236
+ /* ... */
237
+ },
228
238
  },
229
239
  translations: {
230
240
  /* label i18n — see TRANSLATIONS.md */
@@ -236,12 +246,12 @@ export default buildConfig({
236
246
 
237
247
  ### What you can override
238
248
 
239
- | Property | Effect |
240
- |----------|--------|
249
+ | Property | Effect |
250
+ | -------- | --------------------------------------------------- |
241
251
  | `fields` | Add fields or merge with defaults **by field name** |
242
- | `access` | Override access handlers (spread after defaults) |
243
- | `labels` | Collection singular/plural labels |
244
- | `admin` | Group, columns, hidden, etc. |
252
+ | `access` | Override access handlers (spread after defaults) |
253
+ | `labels` | Collection singular/plural labels |
254
+ | `admin` | Group, columns, hidden, etc. |
245
255
 
246
256
  ### Field merge rules
247
257
 
@@ -356,7 +366,11 @@ export default buildConfig({
356
366
  admin: { user: "members" },
357
367
  plugins: [payloadAuthRbacPlugin({ autoModifyUsersCollection: true })],
358
368
  collections: [
359
- { slug: "members", auth: true, fields: [{ name: "email", type: "email", required: true }] },
369
+ {
370
+ slug: "members",
371
+ auth: true,
372
+ fields: [{ name: "email", type: "email", required: true }],
373
+ },
360
374
  ],
361
375
  });
362
376
  ```
@@ -368,7 +382,7 @@ Seed `permission-features` with `code: "members"` to match the slug.
368
382
  ```ts
369
383
  payloadAuthRbacPlugin({
370
384
  autoModifyUsersCollection: false,
371
- })
385
+ });
372
386
  ```
373
387
 
374
388
  You must add `roles`, `isSuperAdmin`, and wire `getPermissionAccess` on the users collection yourself.
@@ -384,7 +398,7 @@ You must add `roles`, `isSuperAdmin`, and wire `getPermissionAccess` on the user
384
398
  5. Create **roles**, configure the matrix, and Save
385
399
  6. Assign **roles** to users
386
400
  7. Bootstrap a **super admin** (seed / DB)
387
- 8. Apply access helpers on app collections — see [UTILS](./UTILS.md)
401
+ 8. Apply access helpers on app collections — see [UTILS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/UTILS.md)
388
402
 
389
403
  ---
390
404
 
@@ -414,13 +428,13 @@ hooks: {
414
428
 
415
429
  ## Quick reference
416
430
 
417
- | Goal | Use |
418
- |------|-----|
419
- | Translate labels | `translations` → [TRANSLATIONS](./TRANSLATIONS.md) |
420
- | Hide / extend fields | `collections.<key>.fields` |
421
- | Change who can CRUD | `collections.<key>.access` |
422
- | Access helpers | [UTILS](./UTILS.md) |
423
- | Setup & plugin config | [README](../README.md) |
424
- | Disable users modification | `autoModifyUsersCollection: false` |
431
+ | Goal | Use |
432
+ | -------------------------- | -------------------------------------------------------------------------------------------------------------------- |
433
+ | Translate labels | `translations` → [TRANSLATIONS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/TRANSLATIONS.md) |
434
+ | Hide / extend fields | `collections.<key>.fields` |
435
+ | Change who can CRUD | `collections.<key>.access` |
436
+ | Access helpers | [UTILS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/UTILS.md) |
437
+ | Setup & plugin config | [README](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/README.md) |
438
+ | Disable users modification | `autoModifyUsersCollection: false` |
425
439
 
426
440
  Working demos: `dev/rbac.ts`, `dev/collections/posts.ts`.
package/docs/TRANSLATIONS.md CHANGED
@@ -457,6 +457,6 @@ Shipped defaults (override via `translations.en`):
457
457
 
458
458
  ## Related docs
459
459
 
460
- - [README](../README.md) — install and quick start
461
- - [COLLECTIONS](./COLLECTIONS.md) — collection schemas and customization
462
- - [UTILS](./UTILS.md) — access helpers
460
+ - [README](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/README.md) — install and quick start
461
+ - [COLLECTIONS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/COLLECTIONS.md) — collection schemas and customization
462
+ - [UTILS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/UTILS.md) — access helpers
package/docs/UTILS.md CHANGED
@@ -28,9 +28,9 @@ Export sources:
28
28
 
29
29
  ```ts
30
30
  type DataScopeOptions = {
31
- createdByField?: string // default: "createdBy"
32
- usersCollectionSlug?: string // default: "users"
33
- }
31
+ createdByField?: string; // default: "createdBy"
32
+ usersCollectionSlug?: string; // default: "users"
33
+ };
34
34
  ```
35
35
 
36
36
  Use this to configure ownership field and users slug for hierarchy logic.
@@ -66,7 +66,7 @@ What it returns:
66
66
  create: getPermissionAccess({
67
67
  featureCode: "posts",
68
68
  actionCode: "create",
69
- })
69
+ });
70
70
 
71
71
  // 2) read + scope (read mode inferred when options exists)
72
72
  read: getPermissionAccess({
@@ -76,7 +76,7 @@ read: getPermissionAccess({
76
76
  createdByField: "createdBy",
77
77
  usersCollectionSlug: "users",
78
78
  },
79
- })
79
+ });
80
80
 
81
81
  // 3) update/delete + document scope (requires mode + collectionSlug)
82
82
  update: getPermissionAccess({
@@ -85,7 +85,7 @@ update: getPermissionAccess({
85
85
  mode: "modify",
86
86
  collectionSlug: "posts",
87
87
  options: { createdByField: "createdBy" },
88
- })
88
+ });
89
89
  ```
90
90
 
91
91
  How it works internally:
@@ -143,8 +143,13 @@ Low-level per-document RBAC + data-scope check.
143
143
  Merge existing `where` with scope constraints.
144
144
 
145
145
  ```ts
146
- const scopeWhere = await getDataScopeReadWhere(req, { createdByField: "createdBy" })
147
- const where = mergeDataScopeWhere({ status: { equals: "published" } }, scopeWhere)
146
+ const scopeWhere = await getDataScopeReadWhere(req, {
147
+ createdByField: "createdBy",
148
+ });
149
+ const where = mergeDataScopeWhere(
150
+ { status: { equals: "published" } },
151
+ scopeWhere,
152
+ );
148
153
  ```
149
154
 
150
155
  ---
@@ -156,9 +161,9 @@ const where = mergeDataScopeWhere({ status: { equals: "published" } }, scopeWher
156
161
  Normalize relationship/id values to string id.
157
162
 
158
163
  ```ts
159
- toID("507f1f77bcf86cd799439011") // "507f1f77bcf86cd799439011"
160
- toID({ id: "507f1f77bcf86cd799439011" }) // "507f1f77bcf86cd799439011"
161
- toID(undefined) // ""
164
+ toID("507f1f77bcf86cd799439011"); // "507f1f77bcf86cd799439011"
165
+ toID({ id: "507f1f77bcf86cd799439011" }); // "507f1f77bcf86cd799439011"
166
+ toID(undefined); // ""
162
167
  ```
163
168
 
164
169
  ---
@@ -203,19 +208,19 @@ Extract nested translation branch by path (example: `"collections.roles"`).
203
208
  Not from `lib/utils`, but often used with access helpers:
204
209
 
205
210
  ```ts
206
- import { CONSTANTS } from "@zealamic/payload-auth-rbac-plugin"
211
+ import { CONSTANTS } from "@zealamic/payload-auth-rbac-plugin";
207
212
 
208
- CONSTANTS.ROLE.DATA_SCOPE
209
- CONSTANTS.ROLE.STATUS
210
- CONSTANTS.PERMISSION.STATUS
211
- CONSTANTS.PERMISSION_ACTION.TYPE
212
- CONSTANTS.USER.PARENT_PATH_SEPARATOR
213
+ CONSTANTS.ROLE.DATA_SCOPE;
214
+ CONSTANTS.ROLE.STATUS;
215
+ CONSTANTS.PERMISSION.STATUS;
216
+ CONSTANTS.PERMISSION_ACTION.TYPE;
217
+ CONSTANTS.USER.PARENT_PATH_SEPARATOR;
213
218
  ```
214
219
 
215
220
  ---
216
221
 
217
222
  ## Related docs
218
223
 
219
- - [README](../README.md) — install and quick start
220
- - [COLLECTIONS](./COLLECTIONS.md) — collection schemas and customization
221
- - [TRANSLATIONS](./TRANSLATIONS.md) — i18n keys
224
+ - [README](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/README.md) — install and quick start
225
+ - [COLLECTIONS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/COLLECTIONS.md) — collection schemas and customization
226
+ - [TRANSLATIONS](https://github.com/zealamic/payload-auth-rbac-plugin/blob/main/docs/TRANSLATIONS.md) — i18n keys
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zealamic/payload-auth-rbac-plugin",
3
- "version": "1.0.0-beta.10",
3
+ "version": "1.0.0-beta.11",
4
4
  "description": "A plugin for Payload CMS to manage authentication and authorization",
5
5
  "license": "MIT",
6
6
  "type": "module",