@backstage/plugin-permission-common 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @backstage/plugin-permission-common
 
+## 0.5.1
+
+### Patch Changes
+
+- Fix for the previous release with missing type declarations.
+- Updated dependencies
+  - @backstage/config@0.1.15
+  - @backstage/errors@0.2.2
+
 ## 0.5.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -0,0 +1,206 @@
+import { Config } from '@backstage/config';
+
+/**
+ * The attributes related to a given permission; these should be generic and widely applicable to
+ * all permissions in the system.
+ * @public
+ */
+declare type PermissionAttributes = {
+    action?: 'create' | 'read' | 'update' | 'delete';
+};
+/**
+ * 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.
+ * @public
+ */
+declare type Permission = {
+    name: string;
+    attributes: PermissionAttributes;
+    resourceType?: string;
+};
+/**
+ * A client interacting with the permission backend can implement this authorizer interface.
+ * @public
+ */
+interface PermissionAuthorizer {
+    authorize(queries: AuthorizeQuery[], options?: AuthorizeRequestOptions): Promise<AuthorizeDecision[]>;
+}
+/**
+ * Options for authorization requests.
+ * @public
+ */
+declare type AuthorizeRequestOptions = {
+    token?: string;
+};
+
+/**
+ * A request with a UUID identifier, so that batched responses can be matched up with the original
+ * requests.
+ * @public
+ */
+declare type Identified<T> = T & {
+    id: string;
+};
+/**
+ * The result of an authorization request.
+ * @public
+ */
+declare enum AuthorizeResult {
+    /**
+     * The authorization request is denied.
+     */
+    DENY = "DENY",
+    /**
+     * The authorization request is allowed.
+     */
+    ALLOW = "ALLOW",
+    /**
+     * The authorization request is allowed if the provided conditions are met.
+     */
+    CONDITIONAL = "CONDITIONAL"
+}
+/**
+ * An individual authorization request for {@link PermissionClient#authorize}.
+ * @public
+ */
+declare type AuthorizeQuery = {
+    permission: Permission;
+    resourceRef?: string;
+};
+/**
+ * A batch of authorization requests from {@link PermissionClient#authorize}.
+ * @public
+ */
+declare type AuthorizeRequest = {
+    items: Identified<AuthorizeQuery>[];
+};
+/**
+ * A condition returned with a CONDITIONAL authorization response.
+ *
+ * Conditions are a reference to a rule defined by a plugin, and parameters to apply the rule. For
+ * example, a rule might be `isOwner` from the catalog-backend, and params may be a list of entity
+ * claims from a identity token.
+ * @public
+ */
+declare type PermissionCondition<TParams extends unknown[] = unknown[]> = {
+    rule: string;
+    params: TParams;
+};
+/**
+ * Utility type to represent an array with 1 or more elements.
+ * @ignore
+ */
+declare type NonEmptyArray<T> = [T, ...T[]];
+/**
+ * Represnts a logical AND for the provided criteria.
+ * @public
+ */
+declare type AllOfCriteria<TQuery> = {
+    allOf: NonEmptyArray<PermissionCriteria<TQuery>>;
+};
+/**
+ * Represnts a logical OR for the provided criteria.
+ * @public
+ */
+declare type AnyOfCriteria<TQuery> = {
+    anyOf: NonEmptyArray<PermissionCriteria<TQuery>>;
+};
+/**
+ * Represents a negation of the provided criteria.
+ * @public
+ */
+declare type NotCriteria<TQuery> = {
+    not: PermissionCriteria<TQuery>;
+};
+/**
+ * Composes several {@link PermissionCondition}s as criteria with a nested AND/OR structure.
+ * @public
+ */
+declare type PermissionCriteria<TQuery> = AllOfCriteria<TQuery> | AnyOfCriteria<TQuery> | NotCriteria<TQuery> | TQuery;
+/**
+ * An individual authorization response from {@link PermissionClient#authorize}.
+ * @public
+ */
+declare type AuthorizeDecision = {
+    result: AuthorizeResult.ALLOW | AuthorizeResult.DENY;
+} | {
+    result: AuthorizeResult.CONDITIONAL;
+    conditions: PermissionCriteria<PermissionCondition>;
+};
+/**
+ * A batch of authorization responses from {@link PermissionClient#authorize}.
+ * @public
+ */
+declare type AuthorizeResponse = {
+    items: Identified<AuthorizeDecision>[];
+};
+
+/**
+ * This is a copy of the core DiscoveryApi, to avoid importing core.
+ *
+ * @public
+ */
+declare type DiscoveryApi = {
+    getBaseUrl(pluginId: string): Promise<string>;
+};
+
+/**
+ * Check if a given permission is related to a create action.
+ * @public
+ */
+declare function isCreatePermission(permission: Permission): boolean;
+/**
+ * Check if a given permission is related to a read action.
+ * @public
+ */
+declare function isReadPermission(permission: Permission): boolean;
+/**
+ * Check if a given permission is related to an update action.
+ * @public
+ */
+declare function isUpdatePermission(permission: Permission): boolean;
+/**
+ * Check if a given permission is related to a delete action.
+ * @public
+ */
+declare function isDeletePermission(permission: Permission): boolean;
+
+/**
+ * An isomorphic client for requesting authorization for Backstage permissions.
+ * @public
+ */
+declare class PermissionClient implements PermissionAuthorizer {
+    private readonly enabled;
+    private readonly discovery;
+    constructor(options: {
+        discovery: DiscoveryApi;
+        config: Config;
+    });
+    /**
+     * Request authorization from the permission-backend for the given set of permissions.
+     *
+     * Authorization requests check that a given Backstage user can perform a protected operation,
+     * potentially for a specific resource (such as a catalog entity). The Backstage identity token
+     * should be included in the `options` if available.
+     *
+     * Permissions can be imported from plugins exposing them, such as `catalogEntityReadPermission`.
+     *
+     * The response will be either ALLOW or DENY when either the permission has no resourceType, or a
+     * resourceRef is provided in the request. For permissions with a resourceType, CONDITIONAL may be
+     * returned if no resourceRef is provided in the request. Conditional responses are intended only
+     * for backends which have access to the data source for permissioned resources, so that filters
+     * can be applied when loading collections of resources.
+     * @public
+     */
+    authorize(queries: AuthorizeQuery[], options?: AuthorizeRequestOptions): Promise<AuthorizeDecision[]>;
+    private getAuthorizationHeader;
+    private assertValidResponse;
+}
+
+export { AllOfCriteria, AnyOfCriteria, AuthorizeDecision, AuthorizeQuery, AuthorizeRequest, AuthorizeRequestOptions, AuthorizeResponse, AuthorizeResult, DiscoveryApi, Identified, NotCriteria, Permission, PermissionAttributes, PermissionAuthorizer, PermissionClient, PermissionCondition, PermissionCriteria, isCreatePermission, isDeletePermission, isReadPermission, isUpdatePermission };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/plugin-permission-common",
   "description": "Isomorphic types and client for Backstage permissions and authorization",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "publishConfig": {
@@ -41,8 +41,8 @@
     "url": "https://github.com/backstage/backstage/issues"
   },
   "dependencies": {
-    "@backstage/config": "^0.1.14",
-    "@backstage/errors": "^0.2.1",
+    "@backstage/config": "^0.1.15",
+    "@backstage/errors": "^0.2.2",
     "cross-fetch": "^3.1.5",
     "uuid": "^8.0.0",
     "zod": "^3.11.6"
@@ -52,6 +52,6 @@
     "@types/jest": "^26.0.7",
     "msw": "^0.35.0"
   },
-  "gitHead": "4805c3d13ce9bfc369e53c271b1b95e722b3b4dc",
+  "gitHead": "e244b348c473700e7d5e5fbcef38bd9f9fd1d0ba",
   "module": "dist/index.esm.js"
 }