permission-common: introduce ResourcePermission type

Signed-off-by: Mike Lewis <mtlewis@users.noreply.github.com>

.changeset/unlucky-schools-heal.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-permission-backend': patch
+---
+
+Add more specific check for policies which return conditional decisions for non-resource permissions.

.changeset/warm-mangos-compete.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-permission-common': patch
+---
+
+Add more specific `Permission` types

plugins/permission-backend/src/service/router.ts

@@ -109,6 +109,12 @@ const handleRequest = async (
           };
         }
 
+        if (!('resourceType' in request.permission)) {
+          throw new Error(
+            `Conditional decision returned from permission policy for non-resource permission ${request.permission.name}`,
+          );
+        }
+
         if (decision.resourceType !== request.permission.resourceType) {
           throw new Error(
             `Invalid resource conditions returned from permission policy for permission ${request.permission.name}`,

plugins/permission-common/api-report.md

@@ -53,6 +53,12 @@ export enum AuthorizeResult {
   DENY = 'DENY',
 }
 
+// @public
+export type BasicPermission = {
+  name: string;
+  attributes: PermissionAttributes;
+};
+
 // @public
 export type DiscoveryApi = {
   getBaseUrl(pluginId: string): Promise<string>;
@@ -81,11 +87,7 @@ export type NotCriteria<TQuery> = {
 };
 
 // @public
-export type Permission = {
-  name: string;
-  attributes: PermissionAttributes;
-  resourceType?: string;
-};
+export type Permission = BasicPermission | ResourcePermission;
 
 // @public
 export type PermissionAttributes = {
@@ -122,4 +124,9 @@ export type PermissionCriteria<TQuery> =
   | AnyOfCriteria<TQuery>
   | NotCriteria<TQuery>
   | TQuery;
+
+// @public
+export type ResourcePermission<T extends string = string> = BasicPermission & {
+  resourceType: T;
+};
 ```

plugins/permission-common/src/types/index.ts

@@ -29,8 +29,10 @@ export type {
 } from './api';
 export type { DiscoveryApi } from './discovery';
 export type {
+  BasicPermission,
   PermissionAttributes,
   Permission,
   PermissionAuthorizer,
+  ResourcePermission,
   AuthorizeRequestOptions,
 } from './permission';

plugins/permission-common/src/types/permission.ts

@@ -28,6 +28,8 @@ export type PermissionAttributes = {
 /**
  * A permission that can be checked through authorization.
  *
+ * @remarks
+ *
  * Permissions are the "what" part of authorization, the action to be performed. This may be reading
  * an entity from the catalog, executing a software template, or any other action a plugin author
  * may wish to protect.
@@ -36,7 +38,13 @@ export type PermissionAttributes = {
  * evaluated using an authorization policy.
  * @public
  */
-export type Permission = {
+export type Permission = BasicPermission | ResourcePermission;
+
+/**
+ * A standard {@link Permission} with no additional capabilities or restrictions.
+ * @public
+ */
+export type BasicPermission = {
   /**
    * The name of the permission.
    */
@@ -47,13 +55,19 @@ export type Permission = {
    * all by name.
    */
   attributes: PermissionAttributes;
+};
+
+/**
+ * ResourcePermissions are {@link Permission}s that can be authorized based on
+ * characteristics of a resource such a catalog entity.
+ * @public
+ */
+export type ResourcePermission<T extends string = string> = BasicPermission & {
   /**
-   * Some permissions can be authorized based on characteristics of a resource
-   * such a catalog entity. For these permissions, the resourceType field
-   * denotes the type of the resource whose resourceRef should be passed when
+   * Denotes the type of the resource whose resourceRef should be passed when
    * authorizing.
    */
-  resourceType?: string;
+  resourceType: T;
 };
 
 /**