Version Packages (next)

plugins/permission-node/CHANGELOG.md

@@ -1,5 +1,81 @@
 # @backstage/plugin-permission-node
 
+## 0.6.0-next.1
+
+### Minor Changes
+
+- 8012ac46a0: **BREAKING**: Stronger typing in `PermissionPolicy` 🎉.
+
+  Previously, it was entirely the responsibility of the `PermissionPolicy` author to only return `CONDITIONAL` decisions for permissions that are associated with a resource, and to return the correct kind of `PermissionCondition` instances inside the decision. Now, the policy authoring helpers provided in this package now ensure that the decision and permission match.
+
+  **For policy authors**: rename and adjust api of `createConditionExports`. Previously, the function returned a factory for creating conditional decisions named `createPolicyDecision`, which had a couple of drawbacks:
+
+  1. The function always creates a _conditional_ policy decision, but this was not reflected in the name.
+  2. Conditional decisions should only ever be returned from `PermissionPolicy#handle` for resource permissions, but there was nothing in the API that encoded this constraint.
+
+  This change addresses the drawbacks above by making the following changes for policy authors:
+
+  - The `createPolicyDecision` method has been renamed to `createConditionalDecision`.
+  - Along with conditions, the method now accepts a permission, which must be a `ResourcePermission`. This is expected to be the handled permission in `PermissionPolicy#handle`, whose type must first be narrowed using methods like `isPermission` and `isResourcePermission`:
+
+  ```typescript
+  class TestPermissionPolicy implements PermissionPolicy {
+    async handle(
+      request: PolicyQuery<Permission>,
+      _user?: BackstageIdentityResponse,
+    ): Promise<PolicyDecision> {
+      if (
+        // Narrow type of `request.permission` to `ResourcePermission<'catalog-entity'>
+        isResourcePermission(request.permission, RESOURCE_TYPE_CATALOG_ENTITY)
+      ) {
+        return createCatalogConditionalDecision(
+          request.permission,
+          catalogConditions.isEntityOwner(
+            _user?.identity.ownershipEntityRefs ?? [],
+          ),
+        );
+      }
+
+      return {
+        result: AuthorizeResult.ALLOW,
+      };
+  ```
+
+  **BREAKING**: when creating `PermissionRule`s, provide a `resourceType`.
+
+  ```diff
+  export const isEntityOwner = createCatalogPermissionRule({
+    name: 'IS_ENTITY_OWNER',
+    description: 'Allow entities owned by the current user',
+  +  resourceType: RESOURCE_TYPE_CATALOG_ENTITY,
+    apply: (resource: Entity, claims: string[]) => {
+      if (!resource.relations) {
+        return false;
+      }
+
+      return resource.relations
+        .filter(relation => relation.type === RELATION_OWNED_BY)
+        .some(relation => claims.includes(relation.targetRef));
+    },
+    toQuery: (claims: string[]) => ({
+      key: 'relations.ownedBy',
+      values: claims,
+    }),
+  });
+  ```
+
+- c98d271466: **BREAKING:**
+
+  - Rename `PolicyAuthorizeQuery` to `PolicyQuery`
+  - Remove `PolicyDecision`, `DefinitivePolicyDecision`, and `ConditionalPolicyDecision`. These types are now exported from `@backstage/plugin-permission-common`
+
+### Patch Changes
+
+- 8012ac46a0: Fix signature of permission rule in test suites
+- Updated dependencies
+  - @backstage/plugin-permission-common@0.6.0-next.0
+  - @backstage/backend-common@0.13.2-next.1
+
 ## 0.5.6-next.0
 
 ### Patch Changes

plugins/permission-node/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/plugin-permission-node",
   "description": "Common permission and authorization utilities for backend plugins",
-  "version": "0.5.6-next.0",
+  "version": "0.6.0-next.1",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "license": "Apache-2.0",
@@ -33,18 +33,18 @@
     "start": "backstage-cli package start"
   },
   "dependencies": {
-    "@backstage/backend-common": "^0.13.2-next.0",
+    "@backstage/backend-common": "^0.13.2-next.1",
     "@backstage/config": "^1.0.0",
     "@backstage/errors": "^1.0.0",
     "@backstage/plugin-auth-node": "^0.2.0-next.0",
-    "@backstage/plugin-permission-common": "^0.5.3",
+    "@backstage/plugin-permission-common": "^0.6.0-next.0",
     "@types/express": "^4.17.6",
     "express": "^4.17.1",
     "express-promise-router": "^4.1.0",
     "zod": "^3.11.6"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.16.1-next.0",
+    "@backstage/cli": "^0.17.0-next.1",
     "@types/supertest": "^2.0.8",
     "msw": "^0.35.0",
     "supertest": "^6.1.3"