Allow for independent permission sets for books stored on multiple shelves #4450

New Issue

OVERLORD · 2026-02-05T08:54:51+03:00

OVERLORD commented

2026-02-05 08:54:51 +03:00

Originally created by @jsarnowski96 on GitHub (Feb 5, 2024).

Describe the feature you'd like

I'm in the middle of migration of our books between old and new shelves and one thing missing I noticed is that when you add a book to more than one shelf, BookStack won't let you independently setup permissions for that book.

Let's say we have book "Documentation" and two shelves and roles named the same way - "Department X" and "Department Y". I want to move that book from some old shelf initially to "Department X" shelf, but I already know that I will have to share this book with "Department Y" role in the near future. The only difference being the scope of permissions - "Department X" should have full read/write access while "Department Y" should only have read-only permission.

Now the problem is that although I can add book "Documentation" to both shelves, book can only have one set of permissions at the same time. If I cascade permissions from shelf "Department X", book wil now have permissions relative to that shelf, also within "Department Y" shelf. meaning if "Department X" shelf allows read/write access only for "Department X" role, members of "Department Y" role won't be able to display that book despite it being assigned to their shelf as well.

Describe the benefits this would bring to existing BookStack users

Allow to share books between shelves with independent, per-shelf permission sets without a need to setup a proxy roles able to access certain resources.

Can the goal of this request already be achieved via other means?

Only via setting up a proxy roles granting access to specific resources or by manually setting up book permissions and assigning proper roles. but when you need to setup a complex system where each department has access to different things or permission scopes, it becomes very problematic to manage and gets out of control fast. not to mention every cascade permission copy erases all customization and you're back to square one.

Have you searched for an existing open/closed issue?

I have searched for existing issues and none cover my fundamental request

How long have you been using BookStack?

1 to 5 years

Additional context

No response

Originally created by @jsarnowski96 on GitHub (Feb 5, 2024). ### Describe the feature you'd like I'm in the middle of migration of our books between old and new shelves and one thing missing I noticed is that when you add a book to more than one shelf, BookStack won't let you independently setup permissions for that book. Let's say we have book "Documentation" and two shelves and roles named the same way - "Department X" and "Department Y". I want to move that book from some old shelf initially to "Department X" shelf, but I already know that I will have to share this book with "Department Y" role in the near future. The only difference being the scope of permissions - "Department X" should have full read/write access while "Department Y" should only have read-only permission. Now the problem is that although I can add book "Documentation" to both shelves, book can only have one set of permissions at the same time. If I cascade permissions from shelf "Department X", book wil now have permissions relative to that shelf, also within "Department Y" shelf. meaning if "Department X" shelf allows read/write access only for "Department X" role, members of "Department Y" role won't be able to display that book despite it being assigned to their shelf as well. ### Describe the benefits this would bring to existing BookStack users Allow to share books between shelves with independent, per-shelf permission sets without a need to setup a proxy roles able to access certain resources. ### Can the goal of this request already be achieved via other means? Only via setting up a proxy roles granting access to specific resources or by manually setting up book permissions and assigning proper roles. but when you need to setup a complex system where each department has access to different things or permission scopes, it becomes very problematic to manage and gets out of control fast. not to mention every cascade permission copy erases all customization and you're back to square one. ### Have you searched for an existing open/closed issue? - [X] I have searched for existing issues and none cover my fundamental request ### How long have you been using BookStack? 1 to 5 years ### Additional context _No response_

OVERLORD added the 🔨 Feature Request label 2026-02-05 08:54:51 +03:00

OVERLORD commented

2026-02-05 08:54:57 +03:00

@ssddanbrown commented on GitHub (Feb 5, 2024):

Thanks for the suggestion @jsarnowski96,
Personally I'm very much not keen on adding any more complication to the permission system.

Sorry if I have not understood, but what stops you manually managing the permissions at the book level instead to set up the desired permissions, instead of copying them down from the shelves? I don't understand why there's a need to create proxy roles if you could manually re-create the merge of permissions for this book.

@ssddanbrown commented on GitHub (Feb 5, 2024): Thanks for the suggestion @jsarnowski96, Personally I'm very much not keen on adding any more complication to the permission system. Sorry if I have not understood, but what stops you manually managing the permissions at the book level instead to set up the desired permissions, instead of copying them down from the shelves? I don't understand why there's a need to create proxy roles if you could manually re-create the merge of permissions for this book.

OVERLORD commented

2026-02-05 08:55:00 +03:00

@jsarnowski96 commented on GitHub (Feb 5, 2024):

@ssddanbrown it's not like something is stopping me, but if you have to manage several dozens of these "loose" books it becomes a slog. every now and then a new book pops up and since I'm unable to keep track of these changes, the fastest way to deal with users not having access to certain resources within their shelf is to cascade permissions. the drawback is obviously a loss of custom permissions in book config.

as for the proxy roles, I use them mostly because we want to limit the amount of users permitted to access certain resources. For example I don't want all people from "Department X" access book "Documentation" from "Department Y" shelf, but only one or two designated persons, while at the same time not allowing them to access any other resource within that shelf, thus creating a proxy role is necessary. you see what I'm getting at? with each such case there's one new proxy role needed and it keeps growing, although refreshed UI in roles tab, which has been introduced in one of the recent releases helps a bit. I realize there's no solution for this particular use-case, I'm just sharing my pain :)

@jsarnowski96 commented on GitHub (Feb 5, 2024): @ssddanbrown it's not like something is stopping me, but if you have to manage several dozens of these "loose" books it becomes a slog. every now and then a new book pops up and since I'm unable to keep track of these changes, the fastest way to deal with users not having access to certain resources within their shelf is to cascade permissions. the drawback is obviously a loss of custom permissions in book config. as for the proxy roles, I use them mostly because we want to limit the amount of users permitted to access certain resources. For example I don't want all people from "Department X" access book "Documentation" from "Department Y" shelf, but only one or two designated persons, while at the same time not allowing them to access any other resource within that shelf, thus creating a proxy role is necessary. you see what I'm getting at? with each such case there's one new proxy role needed and it keeps growing, although refreshed UI in roles tab, which has been introduced in one of the recent releases helps a bit. I realize there's no solution for this particular use-case, I'm just sharing my pain :)

OVERLORD commented

2026-02-05 08:55:04 +03:00

@ssddanbrown commented on GitHub (Feb 5, 2024):

@jsarnowski96 Okay, I'm still not totally clear on the proxy roles but I'm assuming it's more of a complication that adds to the trouble of your scenario rather than a direct solution to core problem area here.

The particular trouble here, is that it sounds like your desire is not even a combination of the shelf permissions, at least within the current core logic of how BookStack treats permissions. I was wondering if a custom command could be used to copy permissions down in a merge-style way, but you really need a change to the core logic, or specific book-permission handling at a shelf level (not aligned to shelves) by the sounds of it.
That's quite a significant addition or change that I definitely wouldn't like to make, nor can I see an smaller scope that could be achieved via a hack.

If it's possible to think of your desired permission goal, in respect to current permission core logic and UI, it might be possible to come up with a hack to take information from books & shelves to apply that, otherwise things get much more complex.

@ssddanbrown commented on GitHub (Feb 5, 2024): @jsarnowski96 Okay, I'm still not totally clear on the proxy roles but I'm assuming it's more of a complication that adds to the trouble of your scenario rather than a direct solution to core problem area here. The particular trouble here, is that it sounds like your desire is not even a combination of the shelf permissions, at least within the current core logic of how BookStack treats permissions. I was wondering if a custom command could be used to copy permissions down in a merge-style way, but you really need a change to the core logic, or specific book-permission handling at a shelf level (not aligned to shelves) by the sounds of it. That's quite a significant addition or change that I definitely wouldn't like to make, nor can I see an smaller scope that could be achieved via a hack. If it's possible to think of your desired permission goal, in respect to current permission core logic and UI, it might be possible to come up with a hack to take information from books & shelves to apply that, otherwise things get much more complex.

OVERLORD commented

2026-02-05 08:55:08 +03:00

@jsarnowski96 commented on GitHub (Feb 5, 2024):

@ssddanbrown I'll try to explain that concept to the best of my ability:

"Department X" shelf has read/write permission override for "Department X" role, containing 5 members
"Department Y" shelf has read/write permission override for "Department Y" role, containing 5 members
in "Department Y" there's a single book "Documentation" which I want to share with two members of "Department X", but at the same time no other documents should be available to them
in order to achieve it, in "Documentation" book custom permission override I have to set rule for read/write access of role "Shared", which contains these two individuals. If I'd set up rule for "Department X", all of its members would have access to that book. on the other hand I cannot assign these two members of "Department X" role to "Department Y" role, because they'd have full access to the entire "Department Y" shelf.

in the end I want to achieve two main goals:

share book with only a fraction of other role's members
limit their access to that and only that book - they shouldn't even see other content except for this book

The particular trouble here, is that it sounds like your desire is not even a combination of the shelf permissions, at least within the current core logic of how BookStack treats permissions. I was wondering if a custom command could be used to copy permissions down in a merge-style way, but you really need a change to the core logic, or specific book-permission handling at a shelf level (not aligned to shelves) by the sounds of it.
That's quite a significant addition or change that I definitely wouldn't like to make, nor can I see an smaller scope that could be achieved via a hack.

If it's possible to think of your desired permission goal, in respect to current permission core logic and UI, it might be possible to come up with a hack to take information from books & shelves to apply that, otherwise things get much more complex.

one thing that came to my mind - let each book DB entity store custom permissions override as separate column/entry, one for each shelf it's assigned to. I'm not exactly familiar with the way you store permissions in the database, but the general concept would be this:

ID, {permissions you normally pass into DB}, book/shelf ID (both being foreign keys)

Now from security POV, depending on the shelf we're currently in and are trying to access the book, BookStack should load in a set of permissions based on that shelf ID (assuming that book is assigned to it). It sure sounds good on paper, but I somehow doubt it'd be that easy to implement in reality.

@jsarnowski96 commented on GitHub (Feb 5, 2024): @ssddanbrown I'll try to explain that concept to the best of my ability: - "Department X" shelf has read/write permission override for "Department X" role, containing 5 members - "Department Y" shelf has read/write permission override for "Department Y" role, containing 5 members - in "Department Y" there's a single book "Documentation" which I want to share with **two members** of "Department X", but at the same time **no other documents** should be available to them - in order to achieve it, in "Documentation" book custom permission override I have to set rule for read/write access of role "Shared", which contains these two individuals. If I'd set up rule for "Department X", all of its members would have access to that book. on the other hand I cannot assign these two members of "Department X" role to "Department Y" role, because they'd have full access to the entire "Department Y" shelf. in the end I want to achieve two main goals: - share book with only a fraction of other role's members - limit their access to that and only that book - they shouldn't even see other content except for this book > The particular trouble here, is that it sounds like your desire is not even a combination of the shelf permissions, at least within the current core logic of how BookStack treats permissions. I was wondering if a custom command could be used to copy permissions down in a merge-style way, but you really need a change to the core logic, or specific book-permission handling at a shelf level (not aligned to shelves) by the sounds of it. That's quite a significant addition or change that I definitely wouldn't like to make, nor can I see an smaller scope that could be achieved via a hack. > If it's possible to think of your desired permission goal, in respect to current permission core logic and UI, it might be possible to come up with a hack to take information from books & shelves to apply that, otherwise things get much more complex. one thing that came to my mind - let each book DB entity store custom permissions override as separate column/entry, one for each shelf it's assigned to. I'm not exactly familiar with the way you store permissions in the database, but the general concept would be this: ID, {permissions you normally pass into DB}, book/shelf ID (both being foreign keys) Now from security POV, depending on the shelf we're currently in and are trying to access the book, BookStack should load in a set of permissions based on that shelf ID (assuming that book is assigned to it). It sure sounds good on paper, but I somehow doubt it'd be that easy to implement in reality.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#4450