@backstage/plugin-catalog-backend 1.0.1-next.0 → 1.1.0-next.3

package/CHANGELOG.md

@@ -1,5 +1,82 @@
 # @backstage/plugin-catalog-backend
 
+## 1.1.0-next.3
+
+### Patch Changes
+
+- 23646e51a5: Use new `PermissionEvaluator#authorizeConditional` method when retrieving permission conditions.
+- 48405ed232: Added `spec.profile.displayName` to search index for Group kinds
+- Updated dependencies
+  - @backstage/plugin-permission-common@0.6.0-next.1
+  - @backstage/plugin-permission-node@0.6.0-next.2
+  - @backstage/backend-common@0.13.2-next.2
+  - @backstage/integration@1.1.0-next.2
+
+## 1.1.0-next.2
+
+### Minor Changes
+
+- bf82edf4c9: Added `/validate-entity` endpoint
+
+### Patch Changes
+
+- 8592cacfd3: Fixed an issue where sometimes entities would have stale relations "stuck" and
+  not getting removed as expected, after the other end of the relation had stopped
+  referring to them.
+- Updated dependencies
+  - @backstage/catalog-model@1.0.1-next.1
+
+## 1.1.0-next.1
+
+### Minor Changes
+
+- 8012ac46a0: **BREAKING (alpha api):** Replace `createCatalogPolicyDecision` export with `createCatalogConditionalDecision`, which accepts a permission parameter of type `ResourcePermission<'catalog-entity'>` along with conditions. The permission passed 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,
+      };
+  ```
+
+- 8012ac46a0: **BREAKING:** Mark CatalogBuilder#addPermissionRules as @alpha.
+- fb02d2d94d: export `locationSpecToLocationEntity`
+
+### Patch Changes
+
+- ada4446733: Specify type of `visibilityPermission` property on collators and collator factories.
+- 1691c6c5c2: Clarify that config locations that emit User and Group kinds now need to declare so in the `catalog.locations.[].rules`
+- 8012ac46a0: Handle changes to @alpha permission-related types.
+
+  - All exported permission rules and conditions now have a `resourceType`.
+  - `createCatalogConditionalDecision` now expects supplied conditions to have the appropriate `resourceType`.
+  - `createCatalogPermissionRule` now expects `resourceType` as part of the supplied rule object.
+  - Introduce new `CatalogPermissionRule` convenience type.
+
+- Updated dependencies
+  - @backstage/integration@1.1.0-next.1
+  - @backstage/plugin-permission-common@0.6.0-next.0
+  - @backstage/plugin-permission-node@0.6.0-next.1
+  - @backstage/plugin-catalog-common@1.0.1-next.1
+  - @backstage/backend-common@0.13.2-next.1
+  - @backstage/plugin-search-common@0.3.3-next.1
+
 ## 1.0.1-next.0
 
 ### Patch Changes
@@ -1394,6 +1471,8 @@
     locations:
       - type: github-multi-org
         target: https://github.myorg.com
+        rules:
+          - allow: [User, Group]
 
     processors:
       githubMultiOrg:

package/README.md

@@ -27,8 +27,7 @@ restoring the plugin, if you previously removed it.
 
 ```bash
 # From your Backstage root directory
-cd packages/backend
-yarn add @backstage/plugin-catalog-backend
+yarn add --cwd packages/backend @backstage/plugin-catalog-backend
 ```
 
 ### Adding the plugin to your `packages/backend`

package/alpha/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-catalog-backend",
-  "version": "1.0.1-next.0",
+  "version": "1.1.0-next.3",
   "main": "../dist/index.cjs.js",
   "types": "../dist/index.alpha.d.ts"
 }

package/dist/index.alpha.d.ts

@@ -9,7 +9,7 @@
 import { CatalogApi } from '@backstage/catalog-client';
 import { CatalogEntityDocument } from '@backstage/plugin-catalog-common';
 import { CompoundEntityRef } from '@backstage/catalog-model';
-import { ConditionalPolicyDecision } from '@backstage/plugin-permission-node';
+import { ConditionalPolicyDecision } from '@backstage/plugin-permission-common';
 import { Conditions } from '@backstage/plugin-permission-node';
 import { Config } from '@backstage/config';
 import { DocumentCollatorFactory } from '@backstage/plugin-search-common';
@@ -17,15 +17,18 @@ import { Entity } from '@backstage/catalog-model';
 import { EntityPolicy } from '@backstage/catalog-model';
 import { GetEntitiesRequest } from '@backstage/catalog-client';
 import { JsonValue } from '@backstage/types';
+import { LocationEntityV1alpha1 } from '@backstage/catalog-model';
 import { Logger } from 'winston';
 import { Permission } from '@backstage/plugin-permission-common';
 import { PermissionAuthorizer } from '@backstage/plugin-permission-common';
 import { PermissionCondition } from '@backstage/plugin-permission-common';
 import { PermissionCriteria } from '@backstage/plugin-permission-common';
+import { PermissionEvaluator } from '@backstage/plugin-permission-common';
 import { PermissionRule } from '@backstage/plugin-permission-node';
 import { PluginDatabaseManager } from '@backstage/backend-common';
 import { PluginEndpointDiscovery } from '@backstage/backend-common';
 import { Readable } from 'stream';
+import { ResourcePermission } from '@backstage/plugin-permission-common';
 import { Router } from 'express';
 import { ScmIntegrationRegistry } from '@backstage/integration';
 import { TokenManager } from '@backstage/backend-common';
@@ -269,8 +272,9 @@ export declare class CatalogBuilder {
      * {@link @backstage/plugin-permission-node#PermissionRule}.
      *
      * @param permissionRules - Additional permission rules
+     * @alpha
      */
-    addPermissionRules(...permissionRules: PermissionRule<Entity, EntitiesSearchFilter, unknown[]>[]): void;
+    addPermissionRules(...permissionRules: CatalogPermissionRule[]): void;
     /**
      * Wires up and returns all of the component parts of the catalog
      */
@@ -285,18 +289,18 @@ export declare class CatalogBuilder {
 }
 
 /**
- * These conditions are used when creating conditional decisions that are returned
- * by authorization policies.
+ * These conditions are used when creating conditional decisions for catalog
+ * entities that are returned by authorization policies.
  *
  * @alpha
  */
 export declare 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[]]>;
+hasAnnotation: PermissionRule<Entity, EntitiesSearchFilter, "catalog-entity", [annotation: string]>;
+hasLabel: PermissionRule<Entity, EntitiesSearchFilter, "catalog-entity", [label: string]>;
+hasMetadata: PermissionRule<Entity, EntitiesSearchFilter, "catalog-entity", [key: string, value?: string | undefined]>;
+hasSpec: PermissionRule<Entity, EntitiesSearchFilter, "catalog-entity", [key: string, value?: string | undefined]>;
+isEntityKind: PermissionRule<Entity, EntitiesSearchFilter, "catalog-entity", [kinds: string[]]>;
+isEntityOwner: PermissionRule<Entity, EntitiesSearchFilter, "catalog-entity", [claims: string[]]>;
 }>;
 
 /** @public */
@@ -305,9 +309,18 @@ export declare type CatalogEnvironment = {
     database: PluginDatabaseManager;
     config: Config;
     reader: UrlReader;
-    permissions: PermissionAuthorizer;
+    permissions: PermissionEvaluator | PermissionAuthorizer;
 };
 
+/**
+ * Convenience type for {@link @backstage/plugin-permission-node#PermissionRule}
+ * instances with the correct resource type, resource, and filter to work with
+ * the catalog.
+ *
+ * @alpha
+ */
+export declare type CatalogPermissionRule<TParams extends unknown[] = unknown[]> = PermissionRule<Entity, EntitiesSearchFilter, 'catalog-entity', TParams>;
+
 /** @public */
 export declare interface CatalogProcessingEngine {
     start(): Promise<void>;
@@ -465,37 +478,46 @@ export declare class CodeOwnersProcessor implements CatalogProcessor {
 }
 
 /**
- * Helper function for creating correctly-typed
- * {@link @backstage/plugin-permission-node#PermissionRule}s for the
- * catalog-backend.
- *
- * @alpha
- */
-export declare const createCatalogPermissionRule: <TParams extends unknown[]>(rule: PermissionRule<Entity, EntitiesSearchFilter, TParams>) => PermissionRule<Entity, EntitiesSearchFilter, TParams>;
-
-/**
- * `createCatalogPolicyDecision` can be used when authoring policies to create
- * conditional decisions.
+ * `createCatalogConditionalDecision` can be used when authoring policies to
+ * create conditional decisions. It requires a permission of type
+ * `ResourcePermission<'catalog-entity'>` to be passed as the first parameter.
+ * It's recommended that you use the provided `isResourcePermission` and
+ * `isPermission` helper methods to narrow the type of the permission passed to
+ * the handle method as shown below.
  *
  * ```
  * // MyAuthorizationPolicy.ts
  * ...
  * import { createCatalogPolicyDecision } from '@backstage/plugin-catalog-backend';
+ * import { RESOURCE_TYPE_CATALOG_ENTITY } from '@backstage/plugin-catalog-common';
  *
  * class MyAuthorizationPolicy implements PermissionPolicy {
  *   async handle(request, user) {
  *     ...
  *
- *     return createCatalogPolicyDecision({
- *       anyOf: [...insert conditions here...],
- *     });
- *   }
+ *     if (isResourcePermission(request.permission, RESOURCE_TYPE_CATALOG_ENTITY)) {
+ *       return createCatalogConditionalDecision(
+ *         request.permission,
+ *         { anyOf: [...insert conditions here...] }
+ *       );
+ *     }
+ *
+ *     ...
  * }
  * ```
  *
  * @alpha
  */
-export declare const createCatalogPolicyDecision: (conditions: PermissionCriteria<PermissionCondition<unknown[]>>) => ConditionalPolicyDecision;
+export declare const createCatalogConditionalDecision: (permission: ResourcePermission<"catalog-entity">, conditions: PermissionCriteria<PermissionCondition<"catalog-entity", unknown[]>>) => ConditionalPolicyDecision;
+
+/**
+ * Helper function for creating correctly-typed
+ * {@link @backstage/plugin-permission-node#PermissionRule}s for the
+ * catalog-backend.
+ *
+ * @alpha
+ */
+export declare const createCatalogPermissionRule: <TParams extends unknown[]>(rule: PermissionRule<Entity, EntitiesSearchFilter, "catalog-entity", TParams>) => PermissionRule<Entity, EntitiesSearchFilter, "catalog-entity", TParams>;
 
 /**
  * Creates a function that returns a random processing interval between minSeconds and maxSeconds.
@@ -551,8 +573,6 @@ export declare class DefaultCatalogCollatorFactory implements DocumentCollatorFa
     private constructor();
     getCollator(): Promise<Readable>;
     private applyArgsToFormat;
-    private isUserEntity;
-    private getDocumentText;
     private execute;
 }
 
@@ -716,6 +736,12 @@ export declare type LocationSpec = {
     presence?: 'optional' | 'required';
 };
 
+/** @public */
+export declare function locationSpecToLocationEntity(opts: {
+    location: LocationSpec;
+    parentEntity?: Entity;
+}): LocationEntityV1alpha1;
+
 /** @public */
 export declare function parseEntityYaml(data: Buffer, location: LocationSpec): Iterable<CatalogProcessorResult>;
 
@@ -726,12 +752,12 @@ export declare function parseEntityYaml(data: Buffer, location: LocationSpec): I
  * @alpha
  */
 export declare const permissionRules: {
-    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[]]>;
+    hasAnnotation: PermissionRule<Entity, EntitiesSearchFilter, "catalog-entity", [annotation: string]>;
+    hasLabel: PermissionRule<Entity, EntitiesSearchFilter, "catalog-entity", [label: string]>;
+    hasMetadata: PermissionRule<Entity, EntitiesSearchFilter, "catalog-entity", [key: string, value?: string | undefined]>;
+    hasSpec: PermissionRule<Entity, EntitiesSearchFilter, "catalog-entity", [key: string, value?: string | undefined]>;
+    isEntityKind: PermissionRule<Entity, EntitiesSearchFilter, "catalog-entity", [kinds: string[]]>;
+    isEntityOwner: PermissionRule<Entity, EntitiesSearchFilter, "catalog-entity", [claims: string[]]>;
 };
 
 /**

package/dist/index.beta.d.ts

@@ -9,7 +9,7 @@
 import { CatalogApi } from '@backstage/catalog-client';
 import { CatalogEntityDocument } from '@backstage/plugin-catalog-common';
 import { CompoundEntityRef } from '@backstage/catalog-model';
-import { ConditionalPolicyDecision } from '@backstage/plugin-permission-node';
+import { ConditionalPolicyDecision } from '@backstage/plugin-permission-common';
 import { Conditions } from '@backstage/plugin-permission-node';
 import { Config } from '@backstage/config';
 import { DocumentCollatorFactory } from '@backstage/plugin-search-common';
@@ -17,15 +17,18 @@ import { Entity } from '@backstage/catalog-model';
 import { EntityPolicy } from '@backstage/catalog-model';
 import { GetEntitiesRequest } from '@backstage/catalog-client';
 import { JsonValue } from '@backstage/types';
+import { LocationEntityV1alpha1 } from '@backstage/catalog-model';
 import { Logger } from 'winston';
 import { Permission } from '@backstage/plugin-permission-common';
 import { PermissionAuthorizer } from '@backstage/plugin-permission-common';
 import { PermissionCondition } from '@backstage/plugin-permission-common';
 import { PermissionCriteria } from '@backstage/plugin-permission-common';
+import { PermissionEvaluator } from '@backstage/plugin-permission-common';
 import { PermissionRule } from '@backstage/plugin-permission-node';
 import { PluginDatabaseManager } from '@backstage/backend-common';
 import { PluginEndpointDiscovery } from '@backstage/backend-common';
 import { Readable } from 'stream';
+import { ResourcePermission } from '@backstage/plugin-permission-common';
 import { Router } from 'express';
 import { ScmIntegrationRegistry } from '@backstage/integration';
 import { TokenManager } from '@backstage/backend-common';
@@ -263,14 +266,7 @@ export declare class CatalogBuilder {
      * @param parser - The custom parser
      */
     setEntityDataParser(parser: CatalogProcessorParser): CatalogBuilder;
-    /**
-     * Adds additional permission rules. Permission rules are used to evaluate
-     * catalog resources against queries. See
-     * {@link @backstage/plugin-permission-node#PermissionRule}.
-     *
-     * @param permissionRules - Additional permission rules
-     */
-    addPermissionRules(...permissionRules: PermissionRule<Entity, EntitiesSearchFilter, unknown[]>[]): void;
+    /* Excluded from this release type: addPermissionRules */
     /**
      * Wires up and returns all of the component parts of the catalog
      */
@@ -292,9 +288,11 @@ export declare type CatalogEnvironment = {
     database: PluginDatabaseManager;
     config: Config;
     reader: UrlReader;
-    permissions: PermissionAuthorizer;
+    permissions: PermissionEvaluator | PermissionAuthorizer;
 };
 
+/* Excluded from this release type: CatalogPermissionRule */
+
 /** @public */
 export declare interface CatalogProcessingEngine {
     start(): Promise<void>;
@@ -451,9 +449,9 @@ export declare class CodeOwnersProcessor implements CatalogProcessor {
     preProcessEntity(entity: Entity, location: LocationSpec): Promise<Entity>;
 }
 
-/* Excluded from this release type: createCatalogPermissionRule */
+/* Excluded from this release type: createCatalogConditionalDecision */
 
-/* Excluded from this release type: createCatalogPolicyDecision */
+/* Excluded from this release type: createCatalogPermissionRule */
 
 /**
  * Creates a function that returns a random processing interval between minSeconds and maxSeconds.
@@ -509,8 +507,6 @@ export declare class DefaultCatalogCollatorFactory implements DocumentCollatorFa
     private constructor();
     getCollator(): Promise<Readable>;
     private applyArgsToFormat;
-    private isUserEntity;
-    private getDocumentText;
     private execute;
 }
 
@@ -674,6 +670,12 @@ export declare type LocationSpec = {
     presence?: 'optional' | 'required';
 };
 
+/** @public */
+export declare function locationSpecToLocationEntity(opts: {
+    location: LocationSpec;
+    parentEntity?: Entity;
+}): LocationEntityV1alpha1;
+
 /** @public */
 export declare function parseEntityYaml(data: Buffer, location: LocationSpec): Iterable<CatalogProcessorResult>;