Export conditional permission policy helpers from catalog-backend (#8966)

* Export conditional permission policy helpers from catalog-backend

Signed-off-by: Joon Park <joonp@spotify.com>

* Rename exports to include 'catalog'

Signed-off-by: Joon Park <joonp@spotify.com>

* Minor comment edits

Co-authored-by: MT Lewis <mtlewis@users.noreply.github.com>
Signed-off-by: Joon Park <joonp@spotify.com>

Co-authored-by: MT Lewis <mtlewis@users.noreply.github.com>

.changeset/swift-panthers-dance.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Export conditional permission policy helpers from catalog-backend

plugins/catalog-backend/api-report.md

@@ -9,6 +9,8 @@ import { Account } from 'aws-sdk/clients/organizations';
 import { BitbucketIntegration } from '@backstage/integration';
 import { CatalogApi } from '@backstage/catalog-client';
 import { CatalogEntitiesRequest } from '@backstage/catalog-client';
+import { ConditionalPolicyDecision } from '@backstage/plugin-permission-node';
+import { Conditions } from '@backstage/plugin-permission-node';
 import { Config } from '@backstage/config';
 import { DocumentCollator } from '@backstage/search-common';
 import { Entity } from '@backstage/catalog-model';
@@ -25,6 +27,8 @@ import { LocationSpec } from '@backstage/catalog-model';
 import { Logger as Logger_2 } from 'winston';
 import { Organizations } from 'aws-sdk';
 import { PermissionAuthorizer } from '@backstage/plugin-permission-common';
+import { PermissionCondition } from '@backstage/plugin-permission-common';
+import { PermissionCriteria } from '@backstage/plugin-permission-common';
 import { PermissionRule } from '@backstage/plugin-permission-node';
 import { PluginDatabaseManager } from '@backstage/backend-common';
 import { PluginEndpointDiscovery } from '@backstage/backend-common';
@@ -270,6 +274,32 @@ export class CatalogBuilder {
   setRefreshIntervalSeconds(seconds: number): CatalogBuilder;
 }
 
+// @public
+export const catalogConditions: Conditions<{
+  hasAnnotation: PermissionRule<
+    Entity,
+    EntitiesSearchFilter,
+    [annotation: string]
+  >;
+  hasLabel: PermissionRule<Entity, EntitiesSearchFilter, [label: string]>;
+  hasMetadata: PermissionRule<
+    Entity,
+    EntitiesSearchFilter,
+    [key: string, value?: string | undefined]
+  >;
+  hasSpec: PermissionRule<
+    Entity,
+    EntitiesSearchFilter,
+    [key: string, value?: string | undefined]
+  >;
+  isEntityKind: PermissionRule<Entity, EntitiesSearchFilter, [kinds: string[]]>;
+  isEntityOwner: PermissionRule<
+    Entity,
+    EntitiesSearchFilter,
+    [claims: string[]]
+  >;
+}>;
+
 // Warning: (ae-missing-release-tag) "CatalogEntityDocument" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
@@ -454,6 +484,11 @@ export const createCatalogPermissionRule: <TParams extends unknown[]>(
   rule: PermissionRule<Entity, EntitiesSearchFilter, TParams>,
 ) => PermissionRule<Entity, EntitiesSearchFilter, TParams>;
 
+// @public
+export const createCatalogPolicyDecision: (
+  conditions: PermissionCriteria<PermissionCondition<unknown[]>>,
+) => ConditionalPolicyDecision;
+
 // Warning: (ae-missing-release-tag) "createRandomRefreshInterval" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public

plugins/catalog-backend/src/permissions/conditionExports.ts

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2022 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { RESOURCE_TYPE_CATALOG_ENTITY } from '@backstage/plugin-catalog-common';
+import { createConditionExports } from '@backstage/plugin-permission-node';
+import { permissionRules } from './rules';
+
+const conditionExports = createConditionExports({
+  pluginId: 'catalog',
+  resourceType: RESOURCE_TYPE_CATALOG_ENTITY,
+  rules: permissionRules,
+});
+
+/**
+ * These conditions are used when creating conditional decisions that are returned
+ * by authorization policies.
+ * @public
+ */
+export const catalogConditions = conditionExports.conditions;
+
+/**
+ * `createCatalogPolicyDecision` can be used when authoring policies to create
+ * conditional decisions.
+ *
+ * ```
+ * // MyAuthorizationPolicy.ts
+ * ...
+ * import { createCatalogPolicyDecision } from '@backstage/plugin-catalog-backend';
+ *
+ * class MyAuthorizationPolicy implements PermissionPolicy {
+ *   async handle(request, user) {
+ *     ...
+ *
+ *     return createCatalogPolicyDecision({
+ *       anyOf: [...insert conditions here...],
+ *     });
+ *   }
+ * }
+ * ```
+ * @public
+ */
+export const createCatalogPolicyDecision =
+  conditionExports.createPolicyDecision;

plugins/catalog-backend/src/permissions/index.ts

@@ -14,4 +14,8 @@
  * limitations under the License.
  */
 
+export {
+  catalogConditions,
+  createCatalogPolicyDecision,
+} from './conditionExports';
 export * from './rules';