feat(core): Refactor how permissions get serialized for sessions into using a new strategy

[DanielBiegler]

Preamble

This is a proof of concept for #3095

Description

Since people are asking for more details on how this works I'll copy the docs here as quick reminder:

/**
 * @description
 * This plugin extends the Admin-API and provides a {@link ChannelRolePermissionResolverStrategy} which
 * fundamentally changes how Vendure resolves {@link Permission}s for {@link User}s.
 *
 * By default with the included {@link DefaultRolePermissionResolverStrategy}
 * Vendure stores and resolves permissions by assigning {@link User}s
 * `N` {@link Role}s of which each role can relate to `M` {@link Channel}s.
 *
 * This works well, but it also means you cannot share roles between channels while restricting
 * your users exclusively to their own channel, because channels are tied to the role.
 *
 * Imagine a scenario where you have two users called `UserA`, `UserB`, two channels called
 * `ChannelA`, `ChannelB` and a `CatalogManager`-Role which has permissions for creating,
 * updating and deleting products. You want `UserA` to only be able to work on products that
 * belong to `ChannelA` and `UserB` should only be allowed to work on `ChannelB`.
 *
 * Sharing of a general `CatalogManager`-Role between these channels is not possible under the
 * default strategy because once you relate both channels to the role, both users will have
 * permissions to access each others channels, looking like so:
 *
 * ```
 * UserA ═══➤ CatalogManager ═╦═➤ ChannelA
 *                            ╚═➤ ChannelB
 * UserB ═══➤ CatalogManager ═╦═➤ ChannelA
 *                            ╚═➤ ChannelB
 * ```
 *
 * This means in order to isolate them from each other you must duplicate and maintain two separate
 * `CatalogManager`-Role like so:
 *
 * ```
 * UserA ═══➤ CatalogManagerA ═══➤ ChannelA
 * UserB ═══➤ CatalogManagerB ═══➤ ChannelB
 * ```
 *
 * This scales badly and makes it hard to maintain for marketplaces with lots of administrators.
 *
 * This plugin replaces the default strategy with {@link ChannelRolePermissionResolverStrategy}
 * which allows you to share roles between channels, while still being able to restrict users
 * to their dedicated channels. Using the previously mentioned example, adding the plugin lets you
 * share the permissions from a role granularly for any channel, like so:
 *
 * ```
 * UserA ═══➤ CatalogManager ═══➤ ChannelA
 * UserB ═══➤ CatalogManager ═══➤ ChannelB
 * UserC ═══➤ CatalogManager ═══➤ ChannelA
 * UserC ═══➤ CatalogManager ═══➤ ChannelB
 * UserD ═══➤ CatalogManager ═══➤ ChannelD
 * ... etc. ...
 * ```
 *
 * This is especially useful for multi vendor marketplaces where each vendor has their own channel with `N` roles respectively.
 *
 * @docsCategory auth
 * @docsPage ChannelRolePlugin
 * @docsWeight 0
 * @since 3.2.0
 */

Breaking changes

Nothing should change with the default strategy but once you use the new strategy there is a migration needed because the plugin introduces a new Entity (ChannelRole) and existing roles will stop working. This makes this feature purely opt-in for people that are interested in multi-vendor setups.

Screenshots

You can add screenshots here if applicable.

ToDo

• New UI dropdown depending on the strategy, on admin creation and update page
• Fix/answer remaining TODO comments
• Migration
• Docs
• Unit tests for new strategy
• E2E tests for new strategy

Checklist

📌 Always:

• I have set a clear title
• My PR is small and contains a single feature
• I have checked my own PR

👍 Most of the time:

• I have added or updated test cases
• I have updated the README if needed

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
docs	✅ Ready (Inspect)	Visit Preview	Mar 12, 2025 0:27am

[sonarqubecloud]

Quality Gate failed

Failed conditions
9.8% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud

[martijnvdbrug]

Do we really need to deprecate this first? This helper isn't exported, so I would say it's ok to just mention in the changelog that you should use configService.authOptions.rolePermissionResolverStrategy.resolvePermissions from now on.

[martijnvdbrug]

I like it already. One question, to mess everything up: Is there any functional benefit of useing DefaultRolePermissionResolverStrategy over the new ChannelRolePermissionResolverStrategy, or would the latter always be better and more flexible?

I know it makes this PR less complex and less breaking, but if there is no functional benefit over the DefaultRolePermissionResolverStrategy, is it worth maintaining for ever? Or would it be better to do a more painful migration now, and be done with it forever?

[DanielBiegler]

FYI: Questions have been answered in private but I'll resurface them here to be visible for future interested parties (cc @mohdbk )

I'm not sure but I do think replacing this with the default role permission resolver strategy would be better

and

Or would it be better to do a more painful migration now, and be done with it forever?

Talked about it with Michael and our consensus is that breaking existing Vendure instances is a non starter, especially since technically nothing is "wrong" with the existing handling of Roles/Permissions, it just doesnt fit marketplaces specifically. Marketplaces are a niche and not the norm, so it feels more correct to have this as purely opt in.

There might come a point in the future where this new channel role strategy becomes the default, like for example the next major Vendure version, but for now keeping it a strict opt-in is a lot nicer to the existing user base. :-)

[vercel]

Deployment failed with the following error:

The provided GitHub repository does not contain the requested branch or commit reference. Please ensure the repository is not empty.

[vercel]

@DanielBiegler is attempting to deploy a commit to the Vendure Team on Vercel.

A member of the Team first needs to authorize it.

[sonarqubecloud]

Quality Gate passed

Issues
18 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud