@backstage/plugin-permission-common - npm Package Compare versions

Comparing version 0.0.0-nightly-20220317022557 to 0.0.0-nightly-20220323023253

CHANGELOG.md

 # @backstage/plugin-permission-common
 
-## 0.0.0-nightly-20220317022557
+## 0.0.0-nightly-20220323023253
 
 ### Patch Changes
 
+- 95284162d6: - Add more specific `Permission` types.
+  - Add `createPermission` helper to infer the appropriate type for some permission input.
+  - Add `isResourcePermission` helper to refine Permissions to ResourcePermissions.
+
+## 0.5.3
+
+### Patch Changes
+
 - f24ef7864e: Minor typo fixes
 - Updated dependencies
-  - @backstage/config@0.0.0-nightly-20220317022557
-  - @backstage/errors@0.0.0-nightly-20220317022557
+  - @backstage/config@1.0.0
+  - @backstage/errors@1.0.0
 
@@ -12,0 +20,0 @@ ## 0.5.2

dist/index.cjs.js

@@ -40,2 +40,8 @@ 'use strict';
 
+function isResourcePermission(permission, resourceType) {
+  if (!("resourceType" in permission)) {
+    return false;
+  }
+  return !resourceType || permission.resourceType === resourceType;
+}
 function isCreatePermission(permission) {
@@ -54,2 +60,22 @@ return permission.attributes.action === "create";
 
+function createPermission({
+  name,
+  attributes,
+  resourceType
+}) {
+  if (resourceType) {
+    return {
+      type: "resource",
+      name,
+      attributes,
+      resourceType
+    };
+  }
+  return {
+    type: "basic",
+    name,
+    attributes
+  };
+}
+
 const permissionCriteriaSchema = zod.z.lazy(() => zod.z.object({
@@ -120,6 +146,8 @@ rule: zod.z.string(),
 exports.PermissionClient = PermissionClient;
+exports.createPermission = createPermission;
 exports.isCreatePermission = isCreatePermission;
 exports.isDeletePermission = isDeletePermission;
 exports.isReadPermission = isReadPermission;
+exports.isResourcePermission = isResourcePermission;
 exports.isUpdatePermission = isUpdatePermission;
 //# sourceMappingURL=index.cjs.js.map

dist/index.d.ts

@@ -12,13 +12,6 @@ import { Config } from '@backstage/config';
 /**
- * A permission that can be checked through authorization.
- *
- * 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.
- *
- * To evaluate authorization, a permission is paired with a Backstage identity (the "who") and
- * evaluated using an authorization policy.
+ * Generic type for building {@link Permission} types.
  * @public
  */
-declare type Permission = {
+declare type PermissionBase<TType extends string, TFields extends object> = {
     /**
@@ -34,10 +27,42 @@ * The name of the permission.
     attributes: PermissionAttributes;
+} & {
     /**
-     * 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
+     * String value indicating the type of the permission (e.g. 'basic',
+     * 'resource'). The allowed authorization flows in the permission system
+     * depend on the type. For example, a `resourceRef` should only be provided
+     * when authorizing permissions of type 'resource'.
+     */
+    type: TType;
+} & TFields;
+/**
+ * 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.
+ *
+ * To evaluate authorization, a permission is paired with a Backstage identity (the "who") and
+ * evaluated using an authorization policy.
+ * @public
+ */
+declare type Permission = BasicPermission | ResourcePermission;
+/**
+ * A standard {@link Permission} with no additional capabilities or restrictions.
+ * @public
+ */
+declare type BasicPermission = PermissionBase<'basic', {}>;
+/**
+ * ResourcePermissions are {@link Permission}s that can be authorized based on
+ * characteristics of a resource such a catalog entity.
+ * @public
+ */
+declare type ResourcePermission<TResourceType extends string = string> = PermissionBase<'resource', {
+    /**
+     * Denotes the type of the resource whose resourceRef should be passed when
      * authorizing.
      */
-    resourceType?: string;
-};
+    resourceType: TResourceType;
+}>;
 /**
@@ -170,2 +195,9 @@ * A client interacting with the permission backend can implement this authorizer interface.
 /**
+ * Check if a given permission is a {@link ResourcePermission}. When
+ * `resourceType` is supplied as the second parameter, also checks if
+ * the permission has the specified resource type.
+ * @public
+ */
+declare function isResourcePermission<T extends string = string>(permission: Permission, resourceType?: T): permission is ResourcePermission<T>;
+/**
  * Check if a given permission is related to a create action.
@@ -192,2 +224,23 @@ * @public
 /**
+ * Utility function for creating a valid {@link ResourcePermission}, inferring
+ * the appropriate type and resource type parameter.
+ *
+ * @public
+ */
+declare function createPermission<TResourceType extends string>(input: {
+    name: string;
+    attributes: PermissionAttributes;
+    resourceType: TResourceType;
+}): ResourcePermission<TResourceType>;
+/**
+ * Utility function for creating a valid {@link BasicPermission}.
+ *
+ * @public
+ */
+declare function createPermission(input: {
+    name: string;
+    attributes: PermissionAttributes;
+}): BasicPermission;
+
+/**
  * An isomorphic client for requesting authorization for Backstage permissions.
@@ -224,2 +277,2 @@ * @public
 
-export { AllOfCriteria, AnyOfCriteria, AuthorizeDecision, AuthorizeQuery, AuthorizeRequest, AuthorizeRequestOptions, AuthorizeResponse, AuthorizeResult, DiscoveryApi, Identified, NotCriteria, Permission, PermissionAttributes, PermissionAuthorizer, PermissionClient, PermissionCondition, PermissionCriteria, isCreatePermission, isDeletePermission, isReadPermission, isUpdatePermission };
+export { AllOfCriteria, AnyOfCriteria, AuthorizeDecision, AuthorizeQuery, AuthorizeRequest, AuthorizeRequestOptions, AuthorizeResponse, AuthorizeResult, BasicPermission, DiscoveryApi, Identified, NotCriteria, Permission, PermissionAttributes, PermissionAuthorizer, PermissionBase, PermissionClient, PermissionCondition, PermissionCriteria, ResourcePermission, createPermission, isCreatePermission, isDeletePermission, isReadPermission, isResourcePermission, isUpdatePermission };

dist/index.esm.js

@@ -13,2 +13,8 @@ import { ResponseError } from '@backstage/errors';
 
+function isResourcePermission(permission, resourceType) {
+  if (!("resourceType" in permission)) {
+    return false;
+  }
+  return !resourceType || permission.resourceType === resourceType;
+}
 function isCreatePermission(permission) {
@@ -27,2 +33,22 @@ return permission.attributes.action === "create";
 
+function createPermission({
+  name,
+  attributes,
+  resourceType
+}) {
+  if (resourceType) {
+    return {
+      type: "resource",
+      name,
+      attributes,
+      resourceType
+    };
+  }
+  return {
+    type: "basic",
+    name,
+    attributes
+  };
+}
+
 const permissionCriteriaSchema = z.lazy(() => z.object({
@@ -91,3 +117,3 @@ rule: z.string(),
 
-export { AuthorizeResult, PermissionClient, isCreatePermission, isDeletePermission, isReadPermission, isUpdatePermission };
+export { AuthorizeResult, PermissionClient, createPermission, isCreatePermission, isDeletePermission, isReadPermission, isResourcePermission, isUpdatePermission };
 //# sourceMappingURL=index.esm.js.map

package.json

 {
   "name": "@backstage/plugin-permission-common",
   "description": "Isomorphic types and client for Backstage permissions and authorization",
-  "version": "0.0.0-nightly-20220317022557",
+  "version": "0.0.0-nightly-20220323023253",
   "main": "dist/index.cjs.js",
@@ -44,4 +44,4 @@ "types": "dist/index.d.ts",
   "dependencies": {
-    "@backstage/config": "^0.0.0-nightly-20220317022557",
-    "@backstage/errors": "^0.0.0-nightly-20220317022557",
+    "@backstage/config": "^1.0.0",
+    "@backstage/errors": "^1.0.0",
     "cross-fetch": "^3.1.5",
@@ -52,3 +52,3 @@ "uuid": "^8.0.0",
   "devDependencies": {
-    "@backstage/cli": "^0.0.0-nightly-20220317022557",
+    "@backstage/cli": "^0.0.0-nightly-20220323023253",
     "@types/jest": "^26.0.7",
@@ -55,0 +55,0 @@ "msw": "^0.35.0"

No alert changes

Improved metrics

Total package byte prevSize

57896

increased by17.09%

Lines of code

544

increased by23.64%

Dependency changes

• + Added@backstage/config@1.3.2(transitive)

• + Added@backstage/errors@1.2.7(transitive)

• + Added@backstage/types@1.2.1(transitive)

• - Removed@backstage/config@0.0.0-nightly-20250114022708(transitive)

• - Removed@backstage/errors@0.0.0-nightly-20250114022708(transitive)

• - Removed@backstage/types@0.0.0-nightly-20250114022708(transitive)

• Updated@backstage/config@^1.0.0

• Updated@backstage/errors@^1.0.0