Add AffectedScope-decorator

Author: fraxachun

.changeset/eleven-zoos-rule.md

@@ -0,0 +1,7 @@
+---
+"@comet/cms-api": minor
+---
+
+Add `@AffectedScope` decorator
+
+See https://docs.comet-dxp.com/docs/core-concepts/content-scope/evaluate-content-scopes#operations-that-require-a-content-scope-independently-of-a-specific-entity

docs/docs/2-core-concepts/1-content-scope/3-evaluate-content-scopes.md

@@ -75,3 +75,24 @@ It's also possible to pass a function which returns the content scope to the `@S
 @ScopedEntity(PageTreeNodeDocumentEntityScopeService)
 export class PredefinedPage extends BaseEntity implements DocumentInterface {
 ```
+
+### Operations that require a content scope independently of a specific entity
+
+**@AffectedScope**
+
+Use this decorator in following cases:
+
+- You don't have an entity to check with `@AffectedEntity`
+- You want to check for a combination of content scope values.
+
+Example:
+
+```ts
+@Query([Product])
+@AffectedScope((args) => ({ country: args.country, department: args.department }))
+async products(@Args("country", { type: () => string }) id: string, @Args("department", { type: () => string }): Promise<Product[]> {
+    // Note: you can trust "country" and "department" being in a valid scope in the sense that the user must have a content scope which is a combination of these dimensions:
+    // [{ country: "AT", department: "main" }]; // ok
+    // [{ country: "AT" }, { department: "main" }]; // not sufficient
+}
+```

packages/api/cms-api/src/user-permissions/auth/user-permissions.guard.spec.ts

@@ -7,6 +7,7 @@ import { DISABLE_COMET_GUARDS_METADATA_KEY } from "../../auth/decorators/disable
 import { AbstractAccessControlService } from "../access-control.service";
 import { ContentScopeService } from "../content-scope.service";
 import { AFFECTED_ENTITY_METADATA_KEY, AffectedEntityMeta } from "../decorators/affected-entity.decorator";
+import { AFFECTED_SCOPE_METADATA_KEY, AffectedScopeMeta } from "../decorators/affected-scope.decorator";
 import { REQUIRED_PERMISSION_METADATA_KEY, RequiredPermissionMetadata } from "../decorators/required-permission.decorator";
 import { SCOPED_ENTITY_METADATA_KEY, ScopedEntityMeta } from "../decorators/scoped-entity.decorator";
 import { CurrentUser } from "../dto/current-user";
@@ -41,12 +42,14 @@ describe("UserPermissionsGuard", () => {
         affectedEntities?: AffectedEntityMeta[];
         scopedEntity?: ScopedEntityMeta<TestEntity>;
         disableCometGuards?: boolean;
+        affectedScope?: AffectedScopeMeta;
     }) => {
         reflector.getAllAndOverride = jest.fn().mockImplementation((decorator: string) => {
             if (decorator === REQUIRED_PERMISSION_METADATA_KEY) return annotations.requiredPermission;
             if (decorator === AFFECTED_ENTITY_METADATA_KEY) return annotations.affectedEntities;
             if (decorator === SCOPED_ENTITY_METADATA_KEY) return annotations.scopedEntity;
             if (decorator === DISABLE_COMET_GUARDS_METADATA_KEY) return annotations.disableCometGuards;
+            if (decorator === AFFECTED_SCOPE_METADATA_KEY) return annotations.affectedScope;
             return false;
         });
     };
@@ -527,4 +530,148 @@ describe("UserPermissionsGuard", () => {
             ),
         ).rejects.toThrowError("Could not get content scope");
     });
+
+    it("allows user by AffectedScope", async () => {
+        mockAnnotations({
+            requiredPermission: {
+                requiredPermission: [permissions.p1],
+                options: undefined,
+            },
+            affectedScope: { argsToScope: (args) => ({ a: args.a }) },
+        });
+        expect(
+            await guard.canActivate(
+                mockContext({
+                    userPermissions: [
+                        {
+                            permission: permissions.p1,
+                            contentScopes: [{ a: 1 }],
+                        },
+                    ],
+                    args: { a: 1 },
+                }),
+            ),
+        ).toBe(true);
+        expect(
+            await guard.canActivate(
+                mockContext({
+                    userPermissions: [
+                        {
+                            permission: permissions.p1,
+                            contentScopes: [{ a: 1 }],
+                        },
+                    ],
+                    args: { a: 1, b: 2 },
+                }),
+            ),
+        ).toBe(true);
+    });
+
+    it("allows user by multidimensional AffectedScope", async () => {
+        mockAnnotations({
+            requiredPermission: {
+                requiredPermission: [permissions.p1],
+                options: undefined,
+            },
+            affectedScope: { argsToScope: (args) => ({ a: args.a, b: args.submittedB }) },
+        });
+        expect(
+            await guard.canActivate(
+                mockContext({
+                    userPermissions: [
+                        {
+                            permission: permissions.p1,
+                            contentScopes: [{ a: 1, b: "2" }],
+                        },
+                    ],
+                    args: { a: 1, submittedB: "2" },
+                }),
+            ),
+        ).toBe(true);
+    });
+
+    it("denies by wrong AffectedScope", async () => {
+        mockAnnotations({
+            requiredPermission: {
+                requiredPermission: [permissions.p1],
+                options: undefined,
+            },
+            affectedScope: { argsToScope: (args) => ({ a: args.a }) },
+        });
+        expect(
+            await guard.canActivate(
+                mockContext({
+                    userPermissions: [
+                        {
+                            permission: permissions.p1,
+                            contentScopes: [{ a: 1 }],
+                        },
+                    ],
+                    args: { a: 2 },
+                }),
+            ),
+        ).toBe(false);
+        expect(
+            await guard.canActivate(
+                mockContext({
+                    userPermissions: [
+                        {
+                            permission: permissions.p1,
+                            contentScopes: [{ a: 1 }],
+                        },
+                    ],
+                    args: { a: "1" },
+                }),
+            ),
+        ).toBe(false);
+    });
+
+    it("denies by wrong multidimensional AffectedScope", async () => {
+        mockAnnotations({
+            requiredPermission: {
+                requiredPermission: [permissions.p1],
+                options: undefined,
+            },
+            affectedScope: { argsToScope: (args) => ({ a: args.a, b: args.b }) },
+        });
+        expect(
+            await guard.canActivate(
+                mockContext({
+                    userPermissions: [
+                        {
+                            permission: permissions.p1,
+                            contentScopes: [{ a: 1, b: "2" }],
+                        },
+                    ],
+                    args: { a: 1 },
+                }),
+            ),
+        ).toBe(false);
+        expect(
+            await guard.canActivate(
+                mockContext({
+                    userPermissions: [
+                        {
+                            permission: permissions.p1,
+                            contentScopes: [{ a: 1 }, { b: "2" }], // User must have combination of a and b
+                        },
+                    ],
+                    args: { a: 1, b: "2" },
+                }),
+            ),
+        ).toBe(false);
+        expect(
+            await guard.canActivate(
+                mockContext({
+                    userPermissions: [
+                        {
+                            permission: permissions.p1,
+                            contentScopes: [{ a: 1, b: "2" }],
+                        },
+                    ],
+                    args: { a: 1, b: 2 },
+                }),
+            ),
+        ).toBe(false);
+    });
 });

packages/api/cms-api/src/user-permissions/auth/user-permissions.guard.ts

@@ -66,7 +66,7 @@ export class UserPermissionsGuard implements CanActivate {
         } else {
             if (requiredContentScopes.length === 0)
                 throw new Error(
-                    `Could not get content scope. Either pass a scope-argument or add an @AffectedEntity()-decorator or enable skipScopeCheck in the @RequiredPermission()-decorator of ${location}`,
+                    `Could not get content scope. Either pass a scope-argument or add an @AffectedEntity()/@AffectedScope()-decorator or enable skipScopeCheck in the @RequiredPermission()-decorator of ${location}`,
                 );
 
             // requiredContentScopes is an two level array of scopes

packages/api/cms-api/src/user-permissions/content-scope.service.ts

@@ -9,6 +9,7 @@ import { PageTreeService } from "../page-tree/page-tree.service";
 import { SCOPED_ENTITY_METADATA_KEY, ScopedEntityMeta } from "../user-permissions/decorators/scoped-entity.decorator";
 import { ContentScope } from "../user-permissions/interfaces/content-scope.interface";
 import { AFFECTED_ENTITY_METADATA_KEY, AffectedEntityMeta } from "./decorators/affected-entity.decorator";
+import { AFFECTED_SCOPE_METADATA_KEY, AffectedScopeMeta } from "./decorators/affected-scope.decorator";
 
 // TODO Remove service and move into UserPermissionsGuard once ChangesCheckerInterceptor is removed
 @Injectable()
@@ -33,13 +34,23 @@ export class ContentScopeService {
         const args = await this.getArgs(context);
         const location = `${context.getClass().name}::${context.getHandler().name}()`;
 
+        // AffectedEntities
         const affectedEntities = this.reflector.getAllAndOverride<AffectedEntityMeta[]>(AFFECTED_ENTITY_METADATA_KEY, [context.getHandler()]) || [];
         for (const affectedEntity of affectedEntities) {
             contentScopes.push(...(await this.getContentScopesFromEntity(affectedEntity, args, location)));
         }
+
+        // AffectedScope
+        const affectedScope = this.reflector.getAllAndOverride<AffectedScopeMeta>(AFFECTED_SCOPE_METADATA_KEY, [context.getHandler()]) || undefined;
+        if (affectedScope) {
+            contentScopes.push([affectedScope.argsToScope(args) as ContentScope]);
+        }
+
+        // Scope arg
         if (args.scope) {
             contentScopes.push([args.scope as ContentScope]);
         }
+
         return contentScopes;
     }
 

packages/api/cms-api/src/user-permissions/decorators/affected-scope.decorator.ts

@@ -0,0 +1,13 @@
+import { SetMetadata } from "@nestjs/common";
+
+import { type ContentScope } from "../../user-permissions/interfaces/content-scope.interface";
+
+export type AffectedScopeMeta = {
+    argsToScope: (args: Record<string, unknown>) => ContentScope;
+};
+
+export const AFFECTED_SCOPE_METADATA_KEY = "affectedScope";
+
+export const AffectedScope = (argsToScope: AffectedScopeMeta["argsToScope"]): MethodDecorator => {
+    return SetMetadata<string, AffectedScopeMeta>(AFFECTED_SCOPE_METADATA_KEY, { argsToScope });
+};