permission-node: added PermissionRuleAccessor

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/gold-rabbits-change.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-permission-node': patch
+---
+
+Added a new `PermissionRuleAccessor` type that encapsulates a lookup function for permission rules, which can be created by the new `PermissionsRegistryService` via the `getRuleAccessor` method. The `createConditionTransformer` and `createConditionAuthorizer` functions have been adapted to receive these accessors as arguments, with their older counterparts being deprecated.

plugins/permission-node/report.api.md

@@ -78,9 +78,14 @@ export type ConditionTransformer<TQuery> = (
 ) => PermissionCriteria<TQuery>;
 
 // @public
-export const createConditionAuthorizer: <TResource, TQuery>(
+export function createConditionAuthorizer<TResource>(
+  permissionRuleAccessor: PermissionRuleAccessor<TResource>,
+): (decision: PolicyDecision, resource: TResource | undefined) => boolean;
+
+// @public @deprecated (undocumented)
+export function createConditionAuthorizer<TResource, TQuery>(
   rules: PermissionRule<TResource, TQuery, string>[],
-) => (decision: PolicyDecision, resource: TResource | undefined) => boolean;
+): (decision: PolicyDecision, resource: TResource | undefined) => boolean;
 
 // @public
 export function createConditionExports<
@@ -124,12 +129,15 @@ export const createConditionFactory: <
 ) => (params: TParams) => PermissionCondition<TResourceType, TParams>;
 
 // @public
-export const createConditionTransformer: <
+export function createConditionTransformer<TQuery>(
+  permissionRuleAccessor: PermissionRuleAccessor<any, TQuery>,
+): ConditionTransformer<TQuery>;
+
+// @public @deprecated (undocumented)
+export function createConditionTransformer<
   TQuery,
   TRules extends PermissionRule<any, TQuery, string>[],
->(
-  permissionRules: [...TRules],
-) => ConditionTransformer<TQuery>;
+>(permissionRules: [...TRules]): ConditionTransformer<TQuery>;
 
 // @public
 export function createPermissionIntegrationRouter<
@@ -331,6 +339,13 @@ export type PermissionRule<
   toQuery(params: NoInfer_2<TParams>): PermissionCriteria<TQuery>;
 };
 
+// @public
+export type PermissionRuleAccessor<
+  TResource = unknown,
+  TQuery = unknown,
+  TResourceType extends string = string,
+> = (name: string) => PermissionRule<TResource, TQuery, TResourceType>;
+
 // @public
 export type PolicyQuery = {
   permission: Permission;

plugins/permission-node/src/integration/createConditionTransformer.ts

@@ -20,7 +20,7 @@ import {
   PermissionCondition,
   PermissionCriteria,
 } from '@backstage/plugin-permission-common';
-import { PermissionRule } from '../types';
+import { PermissionRule, PermissionRuleAccessor } from '../types';
 import {
   createGetRule,
   isAndCriteria,
@@ -76,13 +76,26 @@ export type ConditionTransformer<TQuery> = (
  *
  * @public
  */
-export const createConditionTransformer = <
+export function createConditionTransformer<TQuery>(
+  permissionRuleAccessor: PermissionRuleAccessor<any, TQuery>,
+): ConditionTransformer<TQuery>;
+/**
+ * @public
+ * @deprecated Use the version of `createConditionTransformer` that accepts a `PermissionRuleAccessor` instead.
+ */
+export function createConditionTransformer<
   TQuery,
   TRules extends PermissionRule<any, TQuery, string>[],
->(
-  permissionRules: [...TRules],
-): ConditionTransformer<TQuery> => {
-  const getRule = createGetRule(permissionRules);
+>(permissionRules: [...TRules]): ConditionTransformer<TQuery>;
+export function createConditionTransformer<TQuery>(
+  permissionRules:
+    | PermissionRule<any, TQuery, string>[]
+    | PermissionRuleAccessor<any, TQuery>,
+): ConditionTransformer<TQuery> {
+  const getRule =
+    typeof permissionRules === 'function'
+      ? permissionRules
+      : createGetRule(permissionRules);
 
   return conditions => mapConditions(conditions, getRule);
-};
+}

plugins/permission-node/src/types.ts

@@ -66,3 +66,20 @@ export type PermissionRule<
    */
   toQuery(params: NoInfer<TParams>): PermissionCriteria<TQuery>;
 };
+
+/**
+ * A function that can be used to look up permission rules by name for a particular resource type.
+ *
+ * @remarks
+ *
+ * Accessed via {@link @backstage/backend-plugin-api#PermissionsRegistryService.getRuleAccessor}.
+ *
+ * Will throw an error if a rule with the provided name does not exist.
+ *
+ * @public
+ */
+export type PermissionRuleAccessor<
+  TResource = unknown,
+  TQuery = unknown,
+  TResourceType extends string = string,
+> = (name: string) => PermissionRule<TResource, TQuery, TResourceType>;