Add AffectedScope-decorator

.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

.changeset/upset-wolves-take.md

@@ -0,0 +1,5 @@
+---
+"@comet/cms-api": minor
+---
+
+Skip undefined values in content scope check

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

@@ -29,7 +29,7 @@ async product(@Args("id", { type: () => ID }) id: string): Promise<Product> {
 ```
 
 ```ts
-@Query([Product])
+@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
@@ -75,3 +75,32 @@ 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
+}
+```
+
+:::info
+Type annotation can either be achieved via generics (`@AffectedScope<ArgsType>((args) => args)`) or by type assignment (`@AffectedScope((args: ArgsType) => args)`)
+:::
+
+:::info
+If a scope value is `undefined` the dimension will be removed before checking.
+:::

packages/api/cms-api/src/index.ts

@@ -270,6 +270,7 @@ export { SentryModule } from "./sentry/sentry.module";
 export { AzureAiTranslatorModule } from "./translation/azure-ai-translator.module";
 export { AbstractAccessControlService } from "./user-permissions/access-control.service";
 export { AffectedEntity, AffectedEntityMeta, AffectedEntityOptions } from "./user-permissions/decorators/affected-entity.decorator";
+export { AffectedScope } from "./user-permissions/decorators/affected-scope.decorator";
 export { DisablePermissionCheck, RequiredPermission } from "./user-permissions/decorators/required-permission.decorator";
 export { SCOPED_ENTITY_METADATA_KEY, ScopedEntity, ScopedEntityMeta } from "./user-permissions/decorators/scoped-entity.decorator";
 export { CurrentUser } from "./user-permissions/dto/current-user";

packages/api/cms-api/src/user-permissions/access-control.service.ts

@@ -9,16 +9,12 @@ import { AccessControlServiceInterface, Permission } from "./user-permissions.ty
 export abstract class AbstractAccessControlService implements AccessControlServiceInterface {
     private checkContentScope(userContentScopes: ContentScope[], targetContentScope: ContentScope): boolean {
         return userContentScopes.some((userContentScope) =>
-            Object.entries(targetContentScope).every(([dimension, targetContentScopeValue]) => {
-                const userContentScopeValue = (userContentScope as Record<string, unknown>)[dimension];
-
-                // Treat null and undefined the same
-                if (userContentScopeValue == null && targetContentScopeValue == null) {
-                    return true;
-                }
-
-                return userContentScopeValue === targetContentScopeValue;
-            }),
+            Object.entries(targetContentScope)
+                .filter(([_dimension, targetContentScopeValue]) => targetContentScopeValue !== undefined)
+                .every(([dimension, targetContentScopeValue]) => {
+                    const userContentScopeValue = (userContentScope as Record<string, unknown>)[dimension];
+                    return userContentScopeValue === targetContentScopeValue;
+                }),
         );
     }
     isAllowed(user: CurrentUser, permission: Permission, contentScope?: ContentScope): boolean {

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;
         });
     };
@@ -263,6 +266,22 @@ describe("UserPermissionsGuard", () => {
                 }),
             ),
         ).toBe(true); // It is explicitly allowed to have a partial scope (e.g. for operations using ScopeParts). To prevent allowing empty objects, the shape of the content scope object must be checked in another place (e.g. in the Input-Object of a graphql-resolver)
+        expect(
+            await guard.canActivate(
+                mockContext({
+                    userPermissions: [{ permission: permissions.p1, contentScopes: [{ a: "a", b: "b" }] }],
+                    args: { scope: { a: "a", b: undefined } },
+                }),
+            ),
+        ).toBe(true); // It is explicitly allowed to have a partial scope (e.g. for operations using ScopeParts). To prevent allowing empty objects, the shape of the content scope object must be checked in another place (e.g. in the Input-Object of a graphql-resolver)
+        expect(
+            await guard.canActivate(
+                mockContext({
+                    userPermissions: [{ permission: permissions.p1, contentScopes: [{ a: "a", b: "b" }] }],
+                    args: { scope: { a: "a", b: null } },
+                }),
+            ),
+        ).toBe(false); // null !== undefined
     });
 
     it("allows user with scope when submitted scope is empty", async () => {
@@ -527,4 +546,184 @@ 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("allows scope parts submitted by 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 }, // It is explicitly allowed to have a partial scope (e.g. for operations using ScopeParts). To prevent allowing empty objects, the shape of the content scope object must be checked in another place (e.g. in the Input-Object of a graphql-resolver)
+                }),
+            ),
+        ).toBe(true);
+        expect(
+            await guard.canActivate(
+                mockContext({
+                    userPermissions: [
+                        {
+                            permission: permissions.p1,
+                            contentScopes: [{ a: 1, b: "2" }],
+                        },
+                    ],
+                    args: { a: 1, b: undefined }, // It is explicitly allowed to have a partial scope (e.g. for operations using ScopeParts). To prevent allowing empty objects, the shape of the content scope object must be checked in another place (e.g. in the Input-Object of a graphql-resolver)
+                }),
+            ),
+        ).toBe(true);
+    });
+
+    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, b: null },
+                }),
+            ),
+        ).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 = <T>(argsToScope: (args: T) => ContentScope): MethodDecorator => {
+    return SetMetadata<string, AffectedScopeMeta>(AFFECTED_SCOPE_METADATA_KEY, { argsToScope: argsToScope as AffectedScopeMeta["argsToScope"] });
+};