@backstage/plugin-permission-common 0.0.0-nightly-2021102122312

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @backstage/plugin-permission-common
+
+## 0.0.0-nightly-2021102122312
+### Minor Changes
+
+- 92439056fb: Accept configApi rather than enabled flag in PermissionClient constructor.
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/errors@0.0.0-nightly-2021102122312

package/README.md

@@ -0,0 +1,7 @@
+# @backstage/plugin-permission-common
+
+> NOTE: THIS PACKAGE IS EXPERIMENTAL, HERE BE DRAGONS
+
+Isomorphic types and client for Backstage permissions and authorization. For
+more information, see the [authorization
+PRFC](https://github.com/backstage/backstage/pull/7761).

package/config.d.ts

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2021 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.
+ */
+
+export interface Config {
+  /** Configuration options for Backstage permissions and authorization */
+  permission?: {
+    /**
+     * Whether authorization is enabled in Backstage. Defaults to false, which means authorization
+     * requests will be automatically allowed without invoking the authorization policy.
+     * @visibility frontend
+     */
+    enabled?: boolean;
+  };
+}

package/dist/index.cjs.js

@@ -0,0 +1,119 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var errors = require('@backstage/errors');
+var fetch = require('cross-fetch');
+var uuid = require('uuid');
+var zod = require('zod');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () {
+            return e[k];
+          }
+        });
+      }
+    });
+  }
+  n['default'] = e;
+  return Object.freeze(n);
+}
+
+var fetch__default = /*#__PURE__*/_interopDefaultLegacy(fetch);
+var uuid__namespace = /*#__PURE__*/_interopNamespace(uuid);
+
+exports.AuthorizeResult = void 0;
+(function(AuthorizeResult2) {
+  AuthorizeResult2["DENY"] = "DENY";
+  AuthorizeResult2["ALLOW"] = "ALLOW";
+  AuthorizeResult2["CONDITIONAL"] = "CONDITIONAL";
+})(exports.AuthorizeResult || (exports.AuthorizeResult = {}));
+
+function isCreatePermission(permission) {
+  return permission.attributes.action === "create";
+}
+function isReadPermission(permission) {
+  return permission.attributes.action === "read";
+}
+function isUpdatePermission(permission) {
+  return permission.attributes.action === "update";
+}
+function isDeletePermission(permission) {
+  return permission.attributes.action === "delete";
+}
+
+const permissionCriteriaSchema = zod.z.lazy(() => zod.z.object({
+  rule: zod.z.string(),
+  params: zod.z.array(zod.z.unknown())
+}).or(zod.z.object({anyOf: zod.z.array(permissionCriteriaSchema)})).or(zod.z.object({allOf: zod.z.array(permissionCriteriaSchema)})).or(zod.z.object({not: permissionCriteriaSchema})));
+const responseSchema = zod.z.array(zod.z.object({
+  id: zod.z.string(),
+  result: zod.z.literal(exports.AuthorizeResult.ALLOW).or(zod.z.literal(exports.AuthorizeResult.DENY))
+}).or(zod.z.object({
+  id: zod.z.string(),
+  result: zod.z.literal(exports.AuthorizeResult.CONDITIONAL),
+  conditions: permissionCriteriaSchema
+})));
+class PermissionClient {
+  constructor(options) {
+    var _a;
+    this.discoveryApi = options.discoveryApi;
+    this.enabled = (_a = options.configApi.getOptionalBoolean("permission.enabled")) != null ? _a : false;
+  }
+  async authorize(requests, options) {
+    if (!this.enabled) {
+      return requests.map((_) => ({result: exports.AuthorizeResult.ALLOW}));
+    }
+    const identifiedRequests = requests.map((request) => ({
+      id: uuid__namespace.v4(),
+      ...request
+    }));
+    const permissionApi = await this.discoveryApi.getBaseUrl("permission");
+    const response = await fetch__default['default'](`${permissionApi}/authorize`, {
+      method: "POST",
+      body: JSON.stringify(identifiedRequests),
+      headers: {
+        ...this.getAuthorizationHeader(options == null ? void 0 : options.token),
+        "content-type": "application/json"
+      }
+    });
+    if (!response.ok) {
+      throw await errors.ResponseError.fromResponse(response);
+    }
+    const identifiedResponses = await response.json();
+    this.assertValidResponses(identifiedRequests, identifiedResponses);
+    const responsesById = identifiedResponses.reduce((acc, r) => {
+      acc[r.id] = r;
+      return acc;
+    }, {});
+    return identifiedRequests.map((request) => responsesById[request.id]);
+  }
+  getAuthorizationHeader(token) {
+    return token ? {Authorization: `Bearer ${token}`} : {};
+  }
+  assertValidResponses(requests, json) {
+    const authorizedResponses = responseSchema.parse(json);
+    const responseIds = authorizedResponses.map((r) => r.id);
+    const hasAllRequestIds = requests.every((r) => responseIds.includes(r.id));
+    if (!hasAllRequestIds) {
+      throw new Error("Unexpected authorization response from permission-backend");
+    }
+  }
+}
+
+exports.PermissionClient = PermissionClient;
+exports.isCreatePermission = isCreatePermission;
+exports.isDeletePermission = isDeletePermission;
+exports.isReadPermission = isReadPermission;
+exports.isUpdatePermission = isUpdatePermission;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs.js","sources":["../src/types/api.ts","../src/permissions/util.ts","../src/PermissionClient.ts"],"sourcesContent":["/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Permission } from './permission';\n\n/**\n * A request with a UUID identifier, so that batched responses can be matched up with the original\n * requests.\n * @public\n */\nexport type Identified<T> = T & { id: string };\n\n/**\n * The result of an authorization request.\n * @public\n */\nexport enum AuthorizeResult {\n  /**\n   * The authorization request is denied.\n   */\n  DENY = 'DENY',\n  /**\n   * The authorization request is allowed.\n   */\n  ALLOW = 'ALLOW',\n  /**\n   * The authorization request is allowed if the provided conditions are met.\n   */\n  CONDITIONAL = 'CONDITIONAL',\n}\n\n/**\n * An authorization request for {@link PermissionClient#authorize}.\n * @public\n */\nexport type AuthorizeRequest = {\n  permission: Permission;\n  resourceRef?: string;\n};\n\n/**\n * A condition returned with a CONDITIONAL authorization response.\n *\n * Conditions are a reference to a rule defined by a plugin, and parameters to apply the rule. For\n * example, a rule might be `isOwner` from the catalog-backend, and params may be a list of entity\n * claims from a identity token.\n * @public\n */\nexport type PermissionCondition<TParams extends unknown[] = unknown[]> = {\n  rule: string;\n  params: TParams;\n};\n\n/**\n * Composes several {@link PermissionCondition}s as criteria with a nested AND/OR structure.\n * @public\n */\nexport type PermissionCriteria<TQuery> =\n  | { allOf: PermissionCriteria<TQuery>[] }\n  | { anyOf: PermissionCriteria<TQuery>[] }\n  | { not: PermissionCriteria<TQuery> }\n  | TQuery;\n\n/**\n * An authorization response from {@link PermissionClient#authorize}.\n * @public\n */\nexport type AuthorizeResponse =\n  | { result: AuthorizeResult.ALLOW | AuthorizeResult.DENY }\n  | {\n      result: AuthorizeResult.CONDITIONAL;\n      conditions: PermissionCriteria<PermissionCondition>;\n    };\n","/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Permission } from '../types';\n\n/**\n * Check if a given permission is related to a create action.\n * @public\n */\nexport function isCreatePermission(permission: Permission) {\n  return permission.attributes.action === 'create';\n}\n\n/**\n * Check if a given permission is related to a read action.\n * @public\n */\nexport function isReadPermission(permission: Permission) {\n  return permission.attributes.action === 'read';\n}\n\n/**\n * Check if a given permission is related to an update action.\n * @public\n */\nexport function isUpdatePermission(permission: Permission) {\n  return permission.attributes.action === 'update';\n}\n\n/**\n * Check if a given permission is related to a delete action.\n * @public\n */\nexport function isDeletePermission(permission: Permission) {\n  return permission.attributes.action === 'delete';\n}\n","/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Config } from '@backstage/config';\nimport { ResponseError } from '@backstage/errors';\nimport fetch from 'cross-fetch';\nimport * as uuid from 'uuid';\nimport { z } from 'zod';\nimport {\n  AuthorizeResult,\n  AuthorizeRequest,\n  AuthorizeResponse,\n  Identified,\n  PermissionCriteria,\n  PermissionCondition,\n} from './types/api';\nimport { DiscoveryApi } from './types/discovery';\n\nconst permissionCriteriaSchema: z.ZodSchema<\n  PermissionCriteria<PermissionCondition>\n> = z.lazy(() =>\n  z\n    .object({\n      rule: z.string(),\n      params: z.array(z.unknown()),\n    })\n    .or(z.object({ anyOf: z.array(permissionCriteriaSchema) }))\n    .or(z.object({ allOf: z.array(permissionCriteriaSchema) }))\n    .or(z.object({ not: permissionCriteriaSchema })),\n);\n\nconst responseSchema = z.array(\n  z\n    .object({\n      id: z.string(),\n      result: z\n        .literal(AuthorizeResult.ALLOW)\n        .or(z.literal(AuthorizeResult.DENY)),\n    })\n    .or(\n      z.object({\n        id: z.string(),\n        result: z.literal(AuthorizeResult.CONDITIONAL),\n        conditions: permissionCriteriaSchema,\n      }),\n    ),\n);\n\n/**\n * Options for authorization requests; currently only an optional auth token.\n * @public\n */\nexport type AuthorizeRequestOptions = {\n  token?: string;\n};\n\n/**\n * An isomorphic client for requesting authorization for Backstage permissions.\n * @public\n */\nexport class PermissionClient {\n  private readonly enabled: boolean;\n  private readonly discoveryApi: DiscoveryApi;\n\n  constructor(options: { discoveryApi: DiscoveryApi; configApi: Config }) {\n    this.discoveryApi = options.discoveryApi;\n    this.enabled =\n      options.configApi.getOptionalBoolean('permission.enabled') ?? false;\n  }\n\n  /**\n   * Request authorization from the permission-backend for the given set of permissions.\n   *\n   * Authorization requests check that a given Backstage user can perform a protected operation,\n   * potentially for a specific resource (such as a catalog entity). The Backstage identity token\n   * should be included in the `options` if available.\n   *\n   * Permissions can be imported from plugins exposing them, such as `catalogEntityReadPermission`.\n   *\n   * The response will be either ALLOW or DENY when either the permission has no resourceType, or a\n   * resourceRef is provided in the request. For permissions with a resourceType, CONDITIONAL may be\n   * returned if no resourceRef is provided in the request. Conditional responses are intended only\n   * for backends which have access to the data source for permissioned resources, so that filters\n   * can be applied when loading collections of resources.\n   * @public\n   */\n  async authorize(\n    requests: AuthorizeRequest[],\n    options?: AuthorizeRequestOptions,\n  ): Promise<AuthorizeResponse[]> {\n    // TODO(permissions): it would be great to provide some kind of typing guarantee that\n    // conditional responses will only ever be returned for requests containing a resourceType\n    // but no resourceRef. That way clients who aren't prepared to handle filtering according\n    // to conditions can be guaranteed that they won't unexpectedly get a CONDITIONAL response.\n\n    if (!this.enabled) {\n      return requests.map(_ => ({ result: AuthorizeResult.ALLOW }));\n    }\n\n    const identifiedRequests: Identified<AuthorizeRequest>[] = requests.map(\n      request => ({\n        id: uuid.v4(),\n        ...request,\n      }),\n    );\n\n    const permissionApi = await this.discoveryApi.getBaseUrl('permission');\n    const response = await fetch(`${permissionApi}/authorize`, {\n      method: 'POST',\n      body: JSON.stringify(identifiedRequests),\n      headers: {\n        ...this.getAuthorizationHeader(options?.token),\n        'content-type': 'application/json',\n      },\n    });\n    if (!response.ok) {\n      throw await ResponseError.fromResponse(response);\n    }\n\n    const identifiedResponses = await response.json();\n    this.assertValidResponses(identifiedRequests, identifiedResponses);\n\n    const responsesById = identifiedResponses.reduce((acc, r) => {\n      acc[r.id] = r;\n      return acc;\n    }, {} as Record<string, Identified<AuthorizeResponse>>);\n\n    return identifiedRequests.map(request => responsesById[request.id]);\n  }\n\n  private getAuthorizationHeader(token?: string): Record<string, string> {\n    return token ? { Authorization: `Bearer ${token}` } : {};\n  }\n\n  private assertValidResponses(\n    requests: Identified<AuthorizeRequest>[],\n    json: any,\n  ): asserts json is Identified<AuthorizeResponse>[] {\n    const authorizedResponses = responseSchema.parse(json);\n    const responseIds = authorizedResponses.map(r => r.id);\n    const hasAllRequestIds = requests.every(r => responseIds.includes(r.id));\n    if (!hasAllRequestIds) {\n      throw new Error(\n        'Unexpected authorization response from permission-backend',\n      );\n    }\n  }\n}\n"],"names":["AuthorizeResult","z","uuid","fetch","ResponseError"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BYA;AAAL,UAAK,kBAAL;AAIL,6BAAO;AAIP,8BAAQ;AAIR,oCAAc;AAAA,GAZJA;;4BCPuB,YAAwB;AACzD,SAAO,WAAW,WAAW,WAAW;AAAA;0BAOT,YAAwB;AACvD,SAAO,WAAW,WAAW,WAAW;AAAA;4BAOP,YAAwB;AACzD,SAAO,WAAW,WAAW,WAAW;AAAA;4BAOP,YAAwB;AACzD,SAAO,WAAW,WAAW,WAAW;AAAA;;AChB1C,MAAM,2BAEFC,MAAE,KAAK,MACTA,MACG,OAAO;AAAA,EACN,MAAMA,MAAE;AAAA,EACR,QAAQA,MAAE,MAAMA,MAAE;AAAA,GAEnB,GAAGA,MAAE,OAAO,CAAE,OAAOA,MAAE,MAAM,6BAC7B,GAAGA,MAAE,OAAO,CAAE,OAAOA,MAAE,MAAM,6BAC7B,GAAGA,MAAE,OAAO,CAAE,KAAK;AAGxB,MAAM,iBAAiBA,MAAE,MACvBA,MACG,OAAO;AAAA,EACN,IAAIA,MAAE;AAAA,EACN,QAAQA,MACL,QAAQD,wBAAgB,OACxB,GAAGC,MAAE,QAAQD,wBAAgB;AAAA,GAEjC,GACCC,MAAE,OAAO;AAAA,EACP,IAAIA,MAAE;AAAA,EACN,QAAQA,MAAE,QAAQD,wBAAgB;AAAA,EAClC,YAAY;AAAA;uBAiBU;AAAA,EAI5B,YAAY,SAA4D;AA7E1E;AA8EI,SAAK,eAAe,QAAQ;AAC5B,SAAK,UACH,cAAQ,UAAU,mBAAmB,0BAArC,YAA8D;AAAA;AAAA,QAmB5D,UACJ,UACA,SAC8B;AAM9B,QAAI,CAAC,KAAK,SAAS;AACjB,aAAO,SAAS,IAAI,SAAQ,QAAQA,wBAAgB;AAAA;AAGtD,UAAM,qBAAqD,SAAS,IAClE;AAAY,MACV,IAAIE,gBAAK;AAAA,SACN;AAAA;AAIP,UAAM,gBAAgB,MAAM,KAAK,aAAa,WAAW;AACzD,UAAM,WAAW,MAAMC,0BAAM,GAAG,2BAA2B;AAAA,MACzD,QAAQ;AAAA,MACR,MAAM,KAAK,UAAU;AAAA,MACrB,SAAS;AAAA,WACJ,KAAK,uBAAuB,mCAAS;AAAA,QACxC,gBAAgB;AAAA;AAAA;AAGpB,QAAI,CAAC,SAAS,IAAI;AAChB,YAAM,MAAMC,qBAAc,aAAa;AAAA;AAGzC,UAAM,sBAAsB,MAAM,SAAS;AAC3C,SAAK,qBAAqB,oBAAoB;AAE9C,UAAM,gBAAgB,oBAAoB,OAAO,CAAC,KAAK,MAAM;AAC3D,UAAI,EAAE,MAAM;AACZ,aAAO;AAAA,OACN;AAEH,WAAO,mBAAmB,IAAI,aAAW,cAAc,QAAQ;AAAA;AAAA,EAGzD,uBAAuB,OAAwC;AACrE,WAAO,QAAQ,CAAE,eAAe,UAAU,WAAY;AAAA;AAAA,EAGhD,qBACN,UACA,MACiD;AACjD,UAAM,sBAAsB,eAAe,MAAM;AACjD,UAAM,cAAc,oBAAoB,IAAI,OAAK,EAAE;AACnD,UAAM,mBAAmB,SAAS,MAAM,OAAK,YAAY,SAAS,EAAE;AACpE,QAAI,CAAC,kBAAkB;AACrB,YAAM,IAAI,MACR;AAAA;AAAA;AAAA;;;;;;;;"}

package/dist/index.d.ts

@@ -0,0 +1,165 @@
+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 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 authorization request for {@link PermissionClient#authorize}.
+ * @public
+ */
+declare type AuthorizeRequest = {
+    permission: Permission;
+    resourceRef?: string;
+};
+/**
+ * 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;
+};
+/**
+ * Composes several {@link PermissionCondition}s as criteria with a nested AND/OR structure.
+ * @public
+ */
+declare type PermissionCriteria<TQuery> = {
+    allOf: PermissionCriteria<TQuery>[];
+} | {
+    anyOf: PermissionCriteria<TQuery>[];
+} | {
+    not: PermissionCriteria<TQuery>;
+} | TQuery;
+/**
+ * An authorization response from {@link PermissionClient#authorize}.
+ * @public
+ */
+declare type AuthorizeResponse = {
+    result: AuthorizeResult.ALLOW | AuthorizeResult.DENY;
+} | {
+    result: AuthorizeResult.CONDITIONAL;
+    conditions: PermissionCriteria<PermissionCondition>;
+};
+
+/**
+ * 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;
+
+/**
+ * Options for authorization requests; currently only an optional auth token.
+ * @public
+ */
+declare type AuthorizeRequestOptions = {
+    token?: string;
+};
+/**
+ * An isomorphic client for requesting authorization for Backstage permissions.
+ * @public
+ */
+declare class PermissionClient {
+    private readonly enabled;
+    private readonly discoveryApi;
+    constructor(options: {
+        discoveryApi: DiscoveryApi;
+        configApi: 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(requests: AuthorizeRequest[], options?: AuthorizeRequestOptions): Promise<AuthorizeResponse[]>;
+    private getAuthorizationHeader;
+    private assertValidResponses;
+}
+
+export { AuthorizeRequest, AuthorizeRequestOptions, AuthorizeResponse, AuthorizeResult, DiscoveryApi, Identified, Permission, PermissionAttributes, PermissionClient, PermissionCondition, PermissionCriteria, isCreatePermission, isDeletePermission, isReadPermission, isUpdatePermission };

package/dist/index.esm.js

@@ -0,0 +1,86 @@
+import { ResponseError } from '@backstage/errors';
+import fetch from 'cross-fetch';
+import * as uuid from 'uuid';
+import { z } from 'zod';
+
+var AuthorizeResult;
+(function(AuthorizeResult2) {
+  AuthorizeResult2["DENY"] = "DENY";
+  AuthorizeResult2["ALLOW"] = "ALLOW";
+  AuthorizeResult2["CONDITIONAL"] = "CONDITIONAL";
+})(AuthorizeResult || (AuthorizeResult = {}));
+
+function isCreatePermission(permission) {
+  return permission.attributes.action === "create";
+}
+function isReadPermission(permission) {
+  return permission.attributes.action === "read";
+}
+function isUpdatePermission(permission) {
+  return permission.attributes.action === "update";
+}
+function isDeletePermission(permission) {
+  return permission.attributes.action === "delete";
+}
+
+const permissionCriteriaSchema = z.lazy(() => z.object({
+  rule: z.string(),
+  params: z.array(z.unknown())
+}).or(z.object({anyOf: z.array(permissionCriteriaSchema)})).or(z.object({allOf: z.array(permissionCriteriaSchema)})).or(z.object({not: permissionCriteriaSchema})));
+const responseSchema = z.array(z.object({
+  id: z.string(),
+  result: z.literal(AuthorizeResult.ALLOW).or(z.literal(AuthorizeResult.DENY))
+}).or(z.object({
+  id: z.string(),
+  result: z.literal(AuthorizeResult.CONDITIONAL),
+  conditions: permissionCriteriaSchema
+})));
+class PermissionClient {
+  constructor(options) {
+    var _a;
+    this.discoveryApi = options.discoveryApi;
+    this.enabled = (_a = options.configApi.getOptionalBoolean("permission.enabled")) != null ? _a : false;
+  }
+  async authorize(requests, options) {
+    if (!this.enabled) {
+      return requests.map((_) => ({result: AuthorizeResult.ALLOW}));
+    }
+    const identifiedRequests = requests.map((request) => ({
+      id: uuid.v4(),
+      ...request
+    }));
+    const permissionApi = await this.discoveryApi.getBaseUrl("permission");
+    const response = await fetch(`${permissionApi}/authorize`, {
+      method: "POST",
+      body: JSON.stringify(identifiedRequests),
+      headers: {
+        ...this.getAuthorizationHeader(options == null ? void 0 : options.token),
+        "content-type": "application/json"
+      }
+    });
+    if (!response.ok) {
+      throw await ResponseError.fromResponse(response);
+    }
+    const identifiedResponses = await response.json();
+    this.assertValidResponses(identifiedRequests, identifiedResponses);
+    const responsesById = identifiedResponses.reduce((acc, r) => {
+      acc[r.id] = r;
+      return acc;
+    }, {});
+    return identifiedRequests.map((request) => responsesById[request.id]);
+  }
+  getAuthorizationHeader(token) {
+    return token ? {Authorization: `Bearer ${token}`} : {};
+  }
+  assertValidResponses(requests, json) {
+    const authorizedResponses = responseSchema.parse(json);
+    const responseIds = authorizedResponses.map((r) => r.id);
+    const hasAllRequestIds = requests.every((r) => responseIds.includes(r.id));
+    if (!hasAllRequestIds) {
+      throw new Error("Unexpected authorization response from permission-backend");
+    }
+  }
+}
+
+export { AuthorizeResult, PermissionClient, isCreatePermission, isDeletePermission, isReadPermission, isUpdatePermission };
+//# sourceMappingURL=index.esm.js.map

package/dist/index.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.esm.js","sources":["../src/types/api.ts","../src/permissions/util.ts","../src/PermissionClient.ts"],"sourcesContent":["/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Permission } from './permission';\n\n/**\n * A request with a UUID identifier, so that batched responses can be matched up with the original\n * requests.\n * @public\n */\nexport type Identified<T> = T & { id: string };\n\n/**\n * The result of an authorization request.\n * @public\n */\nexport enum AuthorizeResult {\n  /**\n   * The authorization request is denied.\n   */\n  DENY = 'DENY',\n  /**\n   * The authorization request is allowed.\n   */\n  ALLOW = 'ALLOW',\n  /**\n   * The authorization request is allowed if the provided conditions are met.\n   */\n  CONDITIONAL = 'CONDITIONAL',\n}\n\n/**\n * An authorization request for {@link PermissionClient#authorize}.\n * @public\n */\nexport type AuthorizeRequest = {\n  permission: Permission;\n  resourceRef?: string;\n};\n\n/**\n * A condition returned with a CONDITIONAL authorization response.\n *\n * Conditions are a reference to a rule defined by a plugin, and parameters to apply the rule. For\n * example, a rule might be `isOwner` from the catalog-backend, and params may be a list of entity\n * claims from a identity token.\n * @public\n */\nexport type PermissionCondition<TParams extends unknown[] = unknown[]> = {\n  rule: string;\n  params: TParams;\n};\n\n/**\n * Composes several {@link PermissionCondition}s as criteria with a nested AND/OR structure.\n * @public\n */\nexport type PermissionCriteria<TQuery> =\n  | { allOf: PermissionCriteria<TQuery>[] }\n  | { anyOf: PermissionCriteria<TQuery>[] }\n  | { not: PermissionCriteria<TQuery> }\n  | TQuery;\n\n/**\n * An authorization response from {@link PermissionClient#authorize}.\n * @public\n */\nexport type AuthorizeResponse =\n  | { result: AuthorizeResult.ALLOW | AuthorizeResult.DENY }\n  | {\n      result: AuthorizeResult.CONDITIONAL;\n      conditions: PermissionCriteria<PermissionCondition>;\n    };\n","/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Permission } from '../types';\n\n/**\n * Check if a given permission is related to a create action.\n * @public\n */\nexport function isCreatePermission(permission: Permission) {\n  return permission.attributes.action === 'create';\n}\n\n/**\n * Check if a given permission is related to a read action.\n * @public\n */\nexport function isReadPermission(permission: Permission) {\n  return permission.attributes.action === 'read';\n}\n\n/**\n * Check if a given permission is related to an update action.\n * @public\n */\nexport function isUpdatePermission(permission: Permission) {\n  return permission.attributes.action === 'update';\n}\n\n/**\n * Check if a given permission is related to a delete action.\n * @public\n */\nexport function isDeletePermission(permission: Permission) {\n  return permission.attributes.action === 'delete';\n}\n","/*\n * Copyright 2021 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Config } from '@backstage/config';\nimport { ResponseError } from '@backstage/errors';\nimport fetch from 'cross-fetch';\nimport * as uuid from 'uuid';\nimport { z } from 'zod';\nimport {\n  AuthorizeResult,\n  AuthorizeRequest,\n  AuthorizeResponse,\n  Identified,\n  PermissionCriteria,\n  PermissionCondition,\n} from './types/api';\nimport { DiscoveryApi } from './types/discovery';\n\nconst permissionCriteriaSchema: z.ZodSchema<\n  PermissionCriteria<PermissionCondition>\n> = z.lazy(() =>\n  z\n    .object({\n      rule: z.string(),\n      params: z.array(z.unknown()),\n    })\n    .or(z.object({ anyOf: z.array(permissionCriteriaSchema) }))\n    .or(z.object({ allOf: z.array(permissionCriteriaSchema) }))\n    .or(z.object({ not: permissionCriteriaSchema })),\n);\n\nconst responseSchema = z.array(\n  z\n    .object({\n      id: z.string(),\n      result: z\n        .literal(AuthorizeResult.ALLOW)\n        .or(z.literal(AuthorizeResult.DENY)),\n    })\n    .or(\n      z.object({\n        id: z.string(),\n        result: z.literal(AuthorizeResult.CONDITIONAL),\n        conditions: permissionCriteriaSchema,\n      }),\n    ),\n);\n\n/**\n * Options for authorization requests; currently only an optional auth token.\n * @public\n */\nexport type AuthorizeRequestOptions = {\n  token?: string;\n};\n\n/**\n * An isomorphic client for requesting authorization for Backstage permissions.\n * @public\n */\nexport class PermissionClient {\n  private readonly enabled: boolean;\n  private readonly discoveryApi: DiscoveryApi;\n\n  constructor(options: { discoveryApi: DiscoveryApi; configApi: Config }) {\n    this.discoveryApi = options.discoveryApi;\n    this.enabled =\n      options.configApi.getOptionalBoolean('permission.enabled') ?? false;\n  }\n\n  /**\n   * Request authorization from the permission-backend for the given set of permissions.\n   *\n   * Authorization requests check that a given Backstage user can perform a protected operation,\n   * potentially for a specific resource (such as a catalog entity). The Backstage identity token\n   * should be included in the `options` if available.\n   *\n   * Permissions can be imported from plugins exposing them, such as `catalogEntityReadPermission`.\n   *\n   * The response will be either ALLOW or DENY when either the permission has no resourceType, or a\n   * resourceRef is provided in the request. For permissions with a resourceType, CONDITIONAL may be\n   * returned if no resourceRef is provided in the request. Conditional responses are intended only\n   * for backends which have access to the data source for permissioned resources, so that filters\n   * can be applied when loading collections of resources.\n   * @public\n   */\n  async authorize(\n    requests: AuthorizeRequest[],\n    options?: AuthorizeRequestOptions,\n  ): Promise<AuthorizeResponse[]> {\n    // TODO(permissions): it would be great to provide some kind of typing guarantee that\n    // conditional responses will only ever be returned for requests containing a resourceType\n    // but no resourceRef. That way clients who aren't prepared to handle filtering according\n    // to conditions can be guaranteed that they won't unexpectedly get a CONDITIONAL response.\n\n    if (!this.enabled) {\n      return requests.map(_ => ({ result: AuthorizeResult.ALLOW }));\n    }\n\n    const identifiedRequests: Identified<AuthorizeRequest>[] = requests.map(\n      request => ({\n        id: uuid.v4(),\n        ...request,\n      }),\n    );\n\n    const permissionApi = await this.discoveryApi.getBaseUrl('permission');\n    const response = await fetch(`${permissionApi}/authorize`, {\n      method: 'POST',\n      body: JSON.stringify(identifiedRequests),\n      headers: {\n        ...this.getAuthorizationHeader(options?.token),\n        'content-type': 'application/json',\n      },\n    });\n    if (!response.ok) {\n      throw await ResponseError.fromResponse(response);\n    }\n\n    const identifiedResponses = await response.json();\n    this.assertValidResponses(identifiedRequests, identifiedResponses);\n\n    const responsesById = identifiedResponses.reduce((acc, r) => {\n      acc[r.id] = r;\n      return acc;\n    }, {} as Record<string, Identified<AuthorizeResponse>>);\n\n    return identifiedRequests.map(request => responsesById[request.id]);\n  }\n\n  private getAuthorizationHeader(token?: string): Record<string, string> {\n    return token ? { Authorization: `Bearer ${token}` } : {};\n  }\n\n  private assertValidResponses(\n    requests: Identified<AuthorizeRequest>[],\n    json: any,\n  ): asserts json is Identified<AuthorizeResponse>[] {\n    const authorizedResponses = responseSchema.parse(json);\n    const responseIds = authorizedResponses.map(r => r.id);\n    const hasAllRequestIds = requests.every(r => responseIds.includes(r.id));\n    if (!hasAllRequestIds) {\n      throw new Error(\n        'Unexpected authorization response from permission-backend',\n      );\n    }\n  }\n}\n"],"names":[],"mappings":";;;;;IA6BY;AAAL,UAAK,kBAAL;AAIL,6BAAO;AAIP,8BAAQ;AAIR,oCAAc;AAAA,GAZJ;;4BCPuB,YAAwB;AACzD,SAAO,WAAW,WAAW,WAAW;AAAA;0BAOT,YAAwB;AACvD,SAAO,WAAW,WAAW,WAAW;AAAA;4BAOP,YAAwB;AACzD,SAAO,WAAW,WAAW,WAAW;AAAA;4BAOP,YAAwB;AACzD,SAAO,WAAW,WAAW,WAAW;AAAA;;AChB1C,MAAM,2BAEF,EAAE,KAAK,MACT,EACG,OAAO;AAAA,EACN,MAAM,EAAE;AAAA,EACR,QAAQ,EAAE,MAAM,EAAE;AAAA,GAEnB,GAAG,EAAE,OAAO,CAAE,OAAO,EAAE,MAAM,6BAC7B,GAAG,EAAE,OAAO,CAAE,OAAO,EAAE,MAAM,6BAC7B,GAAG,EAAE,OAAO,CAAE,KAAK;AAGxB,MAAM,iBAAiB,EAAE,MACvB,EACG,OAAO;AAAA,EACN,IAAI,EAAE;AAAA,EACN,QAAQ,EACL,QAAQ,gBAAgB,OACxB,GAAG,EAAE,QAAQ,gBAAgB;AAAA,GAEjC,GACC,EAAE,OAAO;AAAA,EACP,IAAI,EAAE;AAAA,EACN,QAAQ,EAAE,QAAQ,gBAAgB;AAAA,EAClC,YAAY;AAAA;uBAiBU;AAAA,EAI5B,YAAY,SAA4D;AA7E1E;AA8EI,SAAK,eAAe,QAAQ;AAC5B,SAAK,UACH,cAAQ,UAAU,mBAAmB,0BAArC,YAA8D;AAAA;AAAA,QAmB5D,UACJ,UACA,SAC8B;AAM9B,QAAI,CAAC,KAAK,SAAS;AACjB,aAAO,SAAS,IAAI,SAAQ,QAAQ,gBAAgB;AAAA;AAGtD,UAAM,qBAAqD,SAAS,IAClE;AAAY,MACV,IAAI,KAAK;AAAA,SACN;AAAA;AAIP,UAAM,gBAAgB,MAAM,KAAK,aAAa,WAAW;AACzD,UAAM,WAAW,MAAM,MAAM,GAAG,2BAA2B;AAAA,MACzD,QAAQ;AAAA,MACR,MAAM,KAAK,UAAU;AAAA,MACrB,SAAS;AAAA,WACJ,KAAK,uBAAuB,mCAAS;AAAA,QACxC,gBAAgB;AAAA;AAAA;AAGpB,QAAI,CAAC,SAAS,IAAI;AAChB,YAAM,MAAM,cAAc,aAAa;AAAA;AAGzC,UAAM,sBAAsB,MAAM,SAAS;AAC3C,SAAK,qBAAqB,oBAAoB;AAE9C,UAAM,gBAAgB,oBAAoB,OAAO,CAAC,KAAK,MAAM;AAC3D,UAAI,EAAE,MAAM;AACZ,aAAO;AAAA,OACN;AAEH,WAAO,mBAAmB,IAAI,aAAW,cAAc,QAAQ;AAAA;AAAA,EAGzD,uBAAuB,OAAwC;AACrE,WAAO,QAAQ,CAAE,eAAe,UAAU,WAAY;AAAA;AAAA,EAGhD,qBACN,UACA,MACiD;AACjD,UAAM,sBAAsB,eAAe,MAAM;AACjD,UAAM,cAAc,oBAAoB,IAAI,OAAK,EAAE;AACnD,UAAM,mBAAmB,SAAS,MAAM,OAAK,YAAY,SAAS,EAAE;AACpE,QAAI,CAAC,kBAAkB;AACrB,YAAM,IAAI,MACR;AAAA;AAAA;AAAA;;;;"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@backstage/plugin-permission-common",
+  "description": "Isomorphic types and client for Backstage permissions and authorization",
+  "version": "0.0.0-nightly-2021102122312",
+  "main": "dist/index.cjs.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "module": "dist/index.esm.js",
+    "types": "dist/index.d.ts"
+  },
+  "homepage": "https://backstage.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/backstage/backstage",
+    "directory": "plugins/permission-common"
+  },
+  "keywords": [
+    "backstage",
+    "permissions"
+  ],
+  "license": "Apache-2.0",
+  "files": [
+    "dist",
+    "config.d.ts"
+  ],
+  "configSchema": "config.d.ts",
+  "scripts": {
+    "build": "backstage-cli build",
+    "lint": "backstage-cli lint",
+    "test": "backstage-cli test",
+    "prepack": "backstage-cli prepack",
+    "postpack": "backstage-cli postpack",
+    "clean": "backstage-cli clean"
+  },
+  "bugs": {
+    "url": "https://github.com/backstage/backstage/issues"
+  },
+  "dependencies": {
+    "@backstage/config": "^0.1.11",
+    "@backstage/errors": "^0.0.0-nightly-2021102122312",
+    "cross-fetch": "^3.0.6",
+    "uuid": "^8.0.0",
+    "zod": "^3.11.6"
+  },
+  "devDependencies": {
+    "@backstage/cli": "^0.0.0-nightly-2021102122312",
+    "@types/jest": "^26.0.7",
+    "msw": "^0.35.0"
+  },
+  "module": "dist/index.esm.js"
+}