Merge pull request #28677 from backstage/rugvip/permission-refs

permissions: add resources refs and rule accessor

packages/backend-plugin-api/report.api.md

@@ -19,7 +19,9 @@ import { Knex } from 'knex';
 import { Permission } from '@backstage/plugin-permission-common';
 import { PermissionAttributes } from '@backstage/plugin-permission-common';
 import { PermissionEvaluator } from '@backstage/plugin-permission-common';
+import { PermissionResourceRef } from '@backstage/plugin-permission-node';
 import { PermissionRule } from '@backstage/plugin-permission-node';
+import { PermissionRuleset } from '@backstage/plugin-permission-node';
 import { QueryPermissionRequest } from '@backstage/plugin-permission-common';
 import { QueryPermissionResponse } from '@backstage/plugin-permission-common';
 import { Readable } from 'stream';
@@ -466,23 +468,34 @@ export interface LoggerService {
 export interface PermissionsRegistryService {
   addPermissionRules(rules: PermissionRule<any, any, string>[]): void;
   addPermissions(permissions: Permission[]): void;
-  addResourceType<const TResourceType extends string, TResource>(
+  addResourceType<const TResourceType extends string, TResource, TQuery>(
     options: PermissionsRegistryServiceAddResourceTypeOptions<
       TResourceType,
-      TResource
+      TResource,
+      TQuery
     >,
   ): void;
+  getPermissionRuleset<TResourceType extends string, TResource, TQuery>(
+    resourceRef: PermissionResourceRef<TResource, TQuery, TResourceType>,
+  ): PermissionRuleset<TResource, TQuery, TResourceType>;
 }
 
 // @public
 export type PermissionsRegistryServiceAddResourceTypeOptions<
   TResourceType extends string,
   TResource,
+  TQuery,
 > = {
-  resourceType: TResourceType;
+  resourceRef: PermissionResourceRef<TResource, TQuery, TResourceType>;
   permissions?: Array<Permission>;
-  rules: PermissionRule<TResource, any, NoInfer_2<TResourceType>>[];
-  getResources?(resourceRefs: string[]): Promise<Array<TResource | undefined>>;
+  rules: PermissionRule<
+    NoInfer_2<TResource>,
+    NoInfer_2<TQuery>,
+    NoInfer_2<TResourceType>
+  >[];
+  getResources?(
+    resourceRefs: string[],
+  ): Promise<Array<NoInfer_2<TResource> | undefined>>;
 };
 
 // @public

packages/backend-plugin-api/src/services/definitions/PermissionsRegistryService.ts

@@ -15,7 +15,11 @@
  */
 
 import { Permission } from '@backstage/plugin-permission-common';
-import { PermissionRule } from '@backstage/plugin-permission-node';
+import {
+  PermissionResourceRef,
+  PermissionRule,
+  PermissionRuleset,
+} from '@backstage/plugin-permission-node';
 
 /**
  * Prevent use of type parameter from contributing to type inference.
@@ -33,11 +37,12 @@ type NoInfer<T> = T extends infer S ? S : never;
 export type PermissionsRegistryServiceAddResourceTypeOptions<
   TResourceType extends string,
   TResource,
+  TQuery,
 > = {
   /**
-   * The identifier for the resource type.
+   * The {@link @backstage/plugin-permission-node#PermissionResourceRef} that identifies the resource type.
    */
-  resourceType: TResourceType;
+  resourceRef: PermissionResourceRef<TResource, TQuery, TResourceType>;
 
   /**
    * Permissions that are available for this resource type.
@@ -47,7 +52,11 @@ export type PermissionsRegistryServiceAddResourceTypeOptions<
   /**
    * Permission rules that are available for this resource type.
    */
-  rules: PermissionRule<TResource, any, NoInfer<TResourceType>>[];
+  rules: PermissionRule<
+    NoInfer<TResource>,
+    NoInfer<TQuery>,
+    NoInfer<TResourceType>
+  >[];
 
   /**
    * The function used to load associated resources based in the provided
@@ -59,7 +68,9 @@ export type PermissionsRegistryServiceAddResourceTypeOptions<
    * resolve conditional decisions except when requesting resources directly
    * from the plugin.
    */
-  getResources?(resourceRefs: string[]): Promise<Array<TResource | undefined>>;
+  getResources?(
+    resourceRefs: string[],
+  ): Promise<Array<NoInfer<TResource> | undefined>>;
 };
 
 /**
@@ -122,10 +133,22 @@ export interface PermissionsRegistryService {
    * called by the `permission-backend` when authorization conditions relating
    * to this plugin need to be evaluated.
    */
-  addResourceType<const TResourceType extends string, TResource>(
+  addResourceType<const TResourceType extends string, TResource, TQuery>(
     options: PermissionsRegistryServiceAddResourceTypeOptions<
       TResourceType,
-      TResource
+      TResource,
+      TQuery
     >,
   ): void;
+
+  /**
+   * Returns the set of registered rules for this resource.
+   *
+   * @remarks
+   *
+   * Primarily intended for use with {@link @backstage/plugin-permission-node#createConditionAuthorizer} and {@link @backstage/plugin-permission-node#createConditionTransformer}.
+   */
+  getPermissionRuleset<TResourceType extends string, TResource, TQuery>(
+    resourceRef: PermissionResourceRef<TResource, TQuery, TResourceType>,
+  ): PermissionRuleset<TResource, TQuery, TResourceType>;
 }