Add docs for user permissions

docs/docs/content-scope/content-website.md

@@ -53,4 +53,4 @@ You can then use `useContentScope()` to access the currently selected scope, whi
 
 COMET's user permission feature will automatically validate `scope` arguments of GraphQL operations and check if a user has access to the entity's scope. The column must be named `scope` for this to work.
 
-You additionally need `@ScopedEntity` (at entity level) for nested entities. And, for operations without a `scope` argument, you must add `@AffectedEntity` at resolver level.
+For nested entities or operations without a `scope` argument please refer to the [documentation of the User Permissions](/docs/user-permissions/access-control) system which describes how to decorate the resolvers/controllers properly.

docs/docs/content-scope/data-driven-application.md

@@ -44,49 +44,4 @@ const variables = {
 
 ### API: User permissions
 
-Data-driven applications don't benefit much from the COMET scope system. But for user permissions it has its value.
-
-First, an overview of user permissions:
-
--   Every user has permissions that give them access to resolvers (e.g., "products") - not covered here
--   Every user has access to scopes
-
-(Both are defined by rule in `AccessControlService` or can be overridden manually per user in the Admin)
-
--   Every entity belongs to a scope
-
-(The user permission feature checks for every request if the entity scope and the user's allowed scopes match.)
-
-#### @ScopedEntity
-
-Use this decorator at entity level to return the scope of an entity. You might have to load multiple relations for nested data.
-
-```ts
-@ScopedEntity(async (product: Product) => {
-    return {
-        dealer: product.dealer.id,
-    };
-})
-@Entity()
-export class Product extends BaseEntity<Product, "id"> {}
-```
-
-#### @AffectedEntity
-
-Use this decorator at the operation level to specify which entity (and thus scope) is affected by the operation.
-
-```ts
-    @Query(Product)
-    @AffectedEntity(Product)
-    async product(@Args("id", { type: () => ID }) id: string): Promise<Product> {
-        //...
-    }
-```
-
-```ts
-    @Query([Product])
-    @AffectedEntity(Dealer, { idArg: "dealer" })
-    async products(@Args("dealer", { type: () => ID }) dealer: string): Promise<Product[]> {
-        // Note: you can trust "dealer" being in a valid scope, but you need to make sure that your business code restricts this query to the given dealer
-    }
-```
+In data-driven applications, the scope system is primarily used for controlling permissions. For additional information refer to the [User Permissions chapter](/docs/user-permissions/access-control).

docs/docs/logging/index.md

@@ -0,0 +1,6 @@
+---
+title: Logging
+sidebar_position: 8
+---
+
+COMET DXP can be used to create both, content websites and data-driven applications. The usage of the content scope differs considerably between these two use cases.

docs/docs/user-permissions/access-control.md

@@ -0,0 +1,147 @@
+---
+title: Access Control in the API
+sidebar_position: 2
+---
+
+:::note
+
+The term **operation** stands for the locations in which COMET DXP invokes permission checks:
+
+-   Queries/Mutations in GraphQL-resolvers
+-   Routes in REST-controllers
+
+Normally you want to decorate the methods of these classes, however, decorating the whole class is also possible.
+:::
+
+After activating the module, COMET DXP checks every operation for the required permissions and scopes. Therefore it is necessary to decorate the operations to let the system know what to check. COMET DXP then checks if the current user possesses the permission defined in the decorator.
+
+Additionally, the scope of the data in operation will be checked against the scope of the users. To achieve this, the system has to know the scope of the data that is being handled right now.
+
+:::note
+You might also want to check the permissions on field resolvers. Therefore you have to add `guards` to `fieldResolverEnhancers` in the configuration of the GraphQL-module. Please be aware that field resolvers are only checked for permissions but not for scopes.
+:::
+
+## Permission check
+
+**@RequiredPermission**
+
+This decorator is mandatory for all operations. The first parameter of type `string | string[] | "disablePermissionCheck"` configures which permission is necessary to access the decorated operation.
+
+The core of COMET DXP already defines a list of permissions (e.g. `pageTree`, `dam`, `cronJobs`, `userPermissions`). Permissions are defined as plain strings, in the most basic case they represent the main items of the menu bar in the administration panel.
+
+However, if you need a more fine-grained access control you might want to concatenate strings, e.g. `newsRead` or `newsCreate`. Only create as many permissions as really necessary.
+
+:::info
+Future version will support a dot-like notation (e.g. `news` will subsume `news.read` and `news.write`).
+:::
+
+## Scope check
+
+:::caution
+COMET DXP validates the data relevant for the operation, but cannot check if the validated data is finally used. You are responsible for applying the validated data in your operations.
+:::
+
+To evaluate the scope there a two technically very distinctive ways depending on the type of operation:
+
+### Operations that create entities or query lists
+
+If an operation does not handle existing entities the scope has to be passed as an argument. COMET DXP expects the argument to be named `scope` to be able to validate it. Do not forget to apply the `scope` argument in your operation.
+
+### Operations that handle specific entities
+
+**@AffectedEntity**
+
+COMET DXP needs information on which entities are being handled in the operation ("affected entity"). Therefore, every operation of this kind needs to be marked with this decorator.
+
+Use this decorator at the **operation level** to specify which entity (and thus scope) is affected by the operation.
+
+:::info
+By default COMET DXP tries to load the affected entity by id with the value of the submitted id-argument. However, the name of the argument can be altered by the `idArg` setting.
+:::
+
+```ts
+@Query(Product)
+@AffectedEntity(Product)
+async product(@Args("id", { type: () => ID }) id: string): Promise<Product> {
+    //...
+}
+```
+
+```ts
+@Query([Product])
+@AffectedEntity(Dealer, { idArg: "dealerId" })
+async products(@Args("dealerId", { type: () => ID }) dealerId: string): Promise<Product[]> {
+    // Note: you can trust "dealerId" being in a valid scope, but you need to make sure that your business code restricts this query to the given dealer
+}
+```
+
+**@ScopedEntity**
+
+Retrieving the affected entity alone is not sufficient, COMET DXP also needs to know the scope of the entity. The simplest case is when the entity has a field named `scope`. If this is true, this decorator is not necessary.
+
+If the scope is stored in a different field or the entity has a relation to another entity that stores the scope, additional information is required. This is where this decorator comes into play.
+
+Use this decorator at the **entity level** to return the scope of an entity.
+
+```ts
+@ScopedEntity(async (product: Product) => {
+    return {
+        dealer: product.dealer.id,
+    };
+})
+@Entity()
+export class Product extends BaseEntity<Product, "id"> {}
+```
+
+:::info
+You might have to load multiple relations for nested data.
+:::
+
+## Disable permission/scope checks
+
+**skipScopeCheck**
+
+The scope check can be disabled by adding `{skipScopeCheck: true}` as the second argument of the `@RequiredPermission` decorator.
+
+:::caution
+Use this option only when you are sure that checking the scope is not necessary (e.g. the current entity does not have a scope). Do not add it just because it seems cumbersome at the moment to add the correct `AffectedEntity`/`ScopedEntity` decorators.
+:::
+
+:::note
+Try to avoid using the `getCurrentUser` decorator. Instead, you should explicitly send all the data needed in an operation. In the following example, this requires adding `userId` as a scope part as well as passing the data throughout the client. Nevertheless, this leads to a cleaner API design.
+
+```diff
+- @RequiredPermission("products", {skipScopeCheck: true})
++ @RequiredPermission("products")
++ @AffectedEntity(User)
+- async myProducts(@GetCurrentUser() currentUser: CurrentUser): Promise<Product[]> {
++ async productsForUser(@Args("userId", { type: () => ID }) userId: string): Promise<Product[]> {
+      //...
+  }
+```
+
+:::
+
+**@PublicApi** (COMET DXP v6)
+
+`@PublicApi()` can be used to expose a single handler (query, mutation or route) or a whole class (resolver or controller) publicly.
+
+:::caution
+
+Using the decorator at class level causes later added handlers to be automatically public. Prefer using the decorator for single handlers only.
+
+:::
+
+**@DisableGlobalAuthGuard** (COMET DXP v7)
+
+`@DisableGlobalAuthGuard()` disables the global auth guard (`CometAuthGuard`). This may be used if a different authentication method is desired (e.g., basic authentication) for a specific handler or class. It should be used in combination with a custom guard. The custom guard may leverage `@PublicApi` as well to expose handlers publicly.
+
+e.g.:
+
+```typescript
+@DisableGlobalGuard()
+@UseGuards(MyCustomGuard)
+async handlerThatUsesACustomGuard(): {
+    ...
+}
+```

docs/docs/user-permissions/admin.md

@@ -0,0 +1,48 @@
+---
+title: Permissions in Admin
+sidebar_position: 3
+---
+
+:::caution
+Please be aware that there is no access control possible in the admin panel. You have to check every permission and scope in the API. The following functions only assist for showing the correct user interface.
+:::
+
+### CurrentUserProvider
+
+The `CurrentUserProvider` loads the current User from the API and provides the following Hooks:
+
+**useCurrentUser**
+
+You can use this hook to access the current user.
+
+:::note
+The current user object provides `allowedContentScopes` which may be used for the content scope selector.
+:::
+
+:::info
+Try not to use the permissions field of the current user object directly as this is subject to change in future versions.
+:::
+
+**useUserPermissionCheck**
+
+This hook provides a function that behaves like the `isAllowed` function in the API.
+
+```ts
+const isAllowed = useUserPermissionCheck();
+if (isAllowed("pageTree")) {
+    // ...
+}
+```
+
+:::info
+Since this function also checks the content scope, it requires the `ContentScopeProvider` in the rendering tree.
+:::
+
+### MasterMenuData
+
+The `MasterMenuData` data type provides a unified format for
+
+-   the `menu` prop in `MasterMenu`
+-   the `menu` prop in `MasterMenuRoutes`
+
+Regarding user permissions, `MasterMenuData` also provides a `requiredPermission` field. Both of the mentioned components use this field to filter the data.

docs/docs/user-permissions/index.md

@@ -0,0 +1,33 @@
+---
+title: User Permissions
+sidebar_position: 6
+---
+
+While COMET DXP does not provide authentication it handles authorization by providing a User Permissions system.
+
+## Key concepts
+
+The user permissions system
+
+-   streamlines authorization throughout the application
+-   not only checks operations but also the handled data
+-   relies on external user handling
+-   allows assigning permissions by code as well as in the administration panel
+-   offers an administration panel that works out of the box
+
+COMET DXP checks authentication in two dimensions:
+
+**Permissions** are used for access control to specific resolvers or controllers.
+
+**Content Scopes** (also referred to as scopes) are used to control which data is allowed to be handled (see [documentation about content scopes](/docs/content-scope)).
+
+Users in COMET DXP possess permissions and scopes. Every operation is assigned to one or more permissions and handles data that is bound to a scope. The system then just tries to match if the requested permissions and scopes are covered by the user's permissions and scopes.
+
+There are no roles as they can easily be represented as a combination of permissions. Furthermore, the ability to check scopes is much more powerful than just having assigned a role.
+
+## Important types
+
+-   `User` is provided by COMET DXP as an interface so that it's possible to enhance the type by Typescript augmentation. By default, a ` User` object contains the fields `id`, `name` and `email`.
+-   `CurrentUser` is used as a GraphQL-type and is returned by GetCurrentUser(). It's not customizable and enhances the default `User` type with the current permissions and scopes.
+-   `ContentScope` is provided as an interface and should be augmented in the application.
+-   There is no custom type for permissions, they are reflected as plain strings.