@backstage/plugin-permission-common 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @backstage/plugin-permission-common
 
+## 0.4.0
+
+### Minor Changes
+
+- b768259244: **BREAKING**: Authorize API request and response types have been updated. The existing `AuthorizeRequest` and `AuthorizeResponse` types now match the entire request and response objects for the /authorize endpoint, and new types `AuthorizeQuery` and `AuthorizeDecision` have been introduced for individual items in the request and response batches respectively.
+
+  **BREAKING**: PermissionClient has been updated to use the new request and response format in the latest version of @backstage/permission-backend.
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/config@0.1.13
+
+## 0.4.0-next.0
+
+### Minor Changes
+
+- b768259244: **BREAKING**: Authorize API request and response types have been updated. The existing `AuthorizeRequest` and `AuthorizeResponse` types now match the entire request and response objects for the /authorize endpoint, and new types `AuthorizeQuery` and `AuthorizeDecision` have been introduced for individual items in the request and response batches respectively.
+
+  **BREAKING**: PermissionClient has been updated to use the new request and response format in the latest version of @backstage/permission-backend.
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/config@0.1.13-next.0
+
+## 0.3.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/config@0.1.12
+  - @backstage/errors@0.2.0
+
+## 0.3.0
+
+### Minor Changes
+
+- 0e8ec6d974: - Add `PermissionAuthorizer` interface matching `PermissionClient` to allow alternative implementations like the `ServerPermissionClient` in @backstage/plugin-permission-node.
+
+  Breaking Changes:
+
+  - Remove "api" suffixes from constructor parameters in PermissionClient
+
+  ```diff
+    const { config, discovery } = options;
+  -  const permissionClient = new PermissionClient({ discoveryApi: discovery, configApi: config });
+  +  const permissionClient = new PermissionClient({ discovery, config });
+  ```
+
 ## 0.2.0
 
 ### Minor Changes

package/dist/index.cjs.js

@@ -18,26 +18,24 @@ function _interopNamespace(e) {
         var d = Object.getOwnPropertyDescriptor(e, k);
         Object.defineProperty(n, k, d.get ? d : {
           enumerable: true,
-          get: function () {
-            return e[k];
-          }
+          get: function () { return e[k]; }
         });
       }
     });
   }
-  n['default'] = e;
+  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) {
+var AuthorizeResult = /* @__PURE__ */ ((AuthorizeResult2) => {
   AuthorizeResult2["DENY"] = "DENY";
   AuthorizeResult2["ALLOW"] = "ALLOW";
   AuthorizeResult2["CONDITIONAL"] = "CONDITIONAL";
-})(exports.AuthorizeResult || (exports.AuthorizeResult = {}));
+  return AuthorizeResult2;
+})(AuthorizeResult || {});
 
 function isCreatePermission(permission) {
   return permission.attributes.action === "create";
@@ -55,33 +53,37 @@ function isDeletePermission(permission) {
 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
-})));
+}).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.object({
+  items: zod.z.array(zod.z.object({
+    id: zod.z.string(),
+    result: zod.z.literal(AuthorizeResult.ALLOW).or(zod.z.literal(AuthorizeResult.DENY))
+  }).or(zod.z.object({
+    id: zod.z.string(),
+    result: zod.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;
+    this.discovery = options.discovery;
+    this.enabled = (_a = options.config.getOptionalBoolean("permission.enabled")) != null ? _a : false;
   }
-  async authorize(requests, options) {
+  async authorize(queries, options) {
     if (!this.enabled) {
-      return requests.map((_) => ({result: exports.AuthorizeResult.ALLOW}));
+      return queries.map((_) => ({ result: 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`, {
+    const request = {
+      items: queries.map((query) => ({
+        id: uuid__namespace.v4(),
+        ...query
+      }))
+    };
+    const permissionApi = await this.discovery.getBaseUrl("permission");
+    const response = await fetch__default["default"](`${permissionApi}/authorize`, {
       method: "POST",
-      body: JSON.stringify(identifiedRequests),
+      body: JSON.stringify(request),
       headers: {
         ...this.getAuthorizationHeader(options == null ? void 0 : options.token),
         "content-type": "application/json"
@@ -90,27 +92,28 @@ class PermissionClient {
     if (!response.ok) {
       throw await errors.ResponseError.fromResponse(response);
     }
-    const identifiedResponses = await response.json();
-    this.assertValidResponses(identifiedRequests, identifiedResponses);
-    const responsesById = identifiedResponses.reduce((acc, r) => {
+    const responseBody = await response.json();
+    this.assertValidResponse(request, responseBody);
+    const responsesById = responseBody.items.reduce((acc, r) => {
       acc[r.id] = r;
       return acc;
     }, {});
-    return identifiedRequests.map((request) => responsesById[request.id]);
+    return request.items.map((query) => responsesById[query.id]);
   }
   getAuthorizationHeader(token) {
-    return token ? {Authorization: `Bearer ${token}`} : {};
+    return token ? { Authorization: `Bearer ${token}` } : {};
   }
-  assertValidResponses(requests, json) {
+  assertValidResponse(request, json) {
     const authorizedResponses = responseSchema.parse(json);
-    const responseIds = authorizedResponses.map((r) => r.id);
-    const hasAllRequestIds = requests.every((r) => responseIds.includes(r.id));
+    const responseIds = authorizedResponses.items.map((r) => r.id);
+    const hasAllRequestIds = request.items.every((r) => responseIds.includes(r.id));
     if (!hasAllRequestIds) {
       throw new Error("Unexpected authorization response from permission-backend");
     }
   }
 }
 
+exports.AuthorizeResult = AuthorizeResult;
 exports.PermissionClient = PermissionClient;
 exports.isCreatePermission = isCreatePermission;
 exports.isDeletePermission = isDeletePermission;

package/dist/index.cjs.js.map

@@ -1 +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;;;;;;;;"}
+{"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 individual authorization request for {@link PermissionClient#authorize}.\n * @public\n */\nexport type AuthorizeQuery = {\n  permission: Permission;\n  resourceRef?: string;\n};\n\n/**\n * A batch of authorization requests from {@link PermissionClient#authorize}.\n * @public\n */\nexport type AuthorizeRequest = {\n  items: Identified<AuthorizeQuery>[];\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 individual authorization response from {@link PermissionClient#authorize}.\n * @public\n */\nexport type AuthorizeDecision =\n  | { result: AuthorizeResult.ALLOW | AuthorizeResult.DENY }\n  | {\n      result: AuthorizeResult.CONDITIONAL;\n      conditions: PermissionCriteria<PermissionCondition>;\n    };\n\n/**\n * A batch of authorization responses from {@link PermissionClient#authorize}.\n * @public\n */\nexport type AuthorizeResponse = {\n  items: Identified<AuthorizeDecision>[];\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  AuthorizeQuery,\n  AuthorizeDecision,\n  Identified,\n  PermissionCriteria,\n  PermissionCondition,\n  AuthorizeResponse,\n  AuthorizeRequest,\n} from './types/api';\nimport { DiscoveryApi } from './types/discovery';\nimport {\n  PermissionAuthorizer,\n  AuthorizeRequestOptions,\n} from './types/permission';\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.object({\n  items: 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/**\n * An isomorphic client for requesting authorization for Backstage permissions.\n * @public\n */\nexport class PermissionClient implements PermissionAuthorizer {\n  private readonly enabled: boolean;\n  private readonly discovery: DiscoveryApi;\n\n  constructor(options: { discovery: DiscoveryApi; config: Config }) {\n    this.discovery = options.discovery;\n    this.enabled =\n      options.config.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    queries: AuthorizeQuery[],\n    options?: AuthorizeRequestOptions,\n  ): Promise<AuthorizeDecision[]> {\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 queries.map(_ => ({ result: AuthorizeResult.ALLOW }));\n    }\n\n    const request: AuthorizeRequest = {\n      items: queries.map(query => ({\n        id: uuid.v4(),\n        ...query,\n      })),\n    };\n\n    const permissionApi = await this.discovery.getBaseUrl('permission');\n    const response = await fetch(`${permissionApi}/authorize`, {\n      method: 'POST',\n      body: JSON.stringify(request),\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 responseBody = await response.json();\n    this.assertValidResponse(request, responseBody);\n\n    const responsesById = responseBody.items.reduce((acc, r) => {\n      acc[r.id] = r;\n      return acc;\n    }, {} as Record<string, Identified<AuthorizeDecision>>);\n\n    return request.items.map(query => responsesById[query.id]);\n  }\n\n  private getAuthorizationHeader(token?: string): Record<string, string> {\n    return token ? { Authorization: `Bearer ${token}` } : {};\n  }\n\n  private assertValidResponse(\n    request: AuthorizeRequest,\n    json: any,\n  ): asserts json is AuthorizeResponse {\n    const authorizedResponses = responseSchema.parse(json);\n    const responseIds = authorizedResponses.items.map(r => r.id);\n    const hasAllRequestIds = request.items.every(r =>\n      responseIds.includes(r.id),\n    );\n    if (!hasAllRequestIds) {\n      throw new Error(\n        'Unexpected authorization response from permission-backend',\n      );\n    }\n  }\n}\n"],"names":["z","uuid","fetch","ResponseError"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA6BY,oCAAA,qBAAL;AAIL,6BAAO;AAIP,8BAAQ;AAIR,oCAAc;AAZJ;AAAA;;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;;ACV1C,MAAM,2BAEFA,MAAE,KAAK,MACTA,MACG,OAAO;AAAA,EACN,MAAMA,MAAE;AAAA,EACR,QAAQA,MAAE,MAAMA,MAAE;AAAA,GAEnB,GAAGA,MAAE,OAAO,EAAE,OAAOA,MAAE,MAAM,8BAC7B,GAAGA,MAAE,OAAO,EAAE,OAAOA,MAAE,MAAM,8BAC7B,GAAGA,MAAE,OAAO,EAAE,KAAK;AAGxB,MAAM,iBAAiBA,MAAE,OAAO;AAAA,EAC9B,OAAOA,MAAE,MACPA,MACG,OAAO;AAAA,IACN,IAAIA,MAAE;AAAA,IACN,QAAQA,MACL,QAAQ,gBAAgB,OACxB,GAAGA,MAAE,QAAQ,gBAAgB;AAAA,KAEjC,GACCA,MAAE,OAAO;AAAA,IACP,IAAIA,MAAE;AAAA,IACN,QAAQA,MAAE,QAAQ,gBAAgB;AAAA,IAClC,YAAY;AAAA;AAAA;uBAUwC;AAAA,EAI5D,YAAY,SAAsD;AA7EpE;AA8EI,SAAK,YAAY,QAAQ;AACzB,SAAK,UACH,cAAQ,OAAO,mBAAmB,0BAAlC,YAA2D;AAAA;AAAA,QAmBzD,UACJ,SACA,SAC8B;AAM9B,QAAI,CAAC,KAAK,SAAS;AACjB,aAAO,QAAQ,IAAI,UAAQ,QAAQ,gBAAgB;AAAA;AAGrD,UAAM,UAA4B;AAAA,MAChC,OAAO,QAAQ,IAAI;AAAU,QAC3B,IAAIC,gBAAK;AAAA,WACN;AAAA;AAAA;AAIP,UAAM,gBAAgB,MAAM,KAAK,UAAU,WAAW;AACtD,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,eAAe,MAAM,SAAS;AACpC,SAAK,oBAAoB,SAAS;AAElC,UAAM,gBAAgB,aAAa,MAAM,OAAO,CAAC,KAAK,MAAM;AAC1D,UAAI,EAAE,MAAM;AACZ,aAAO;AAAA,OACN;AAEH,WAAO,QAAQ,MAAM,IAAI,WAAS,cAAc,MAAM;AAAA;AAAA,EAGhD,uBAAuB,OAAwC;AACrE,WAAO,QAAQ,EAAE,eAAe,UAAU,YAAY;AAAA;AAAA,EAGhD,oBACN,SACA,MACmC;AACnC,UAAM,sBAAsB,eAAe,MAAM;AACjD,UAAM,cAAc,oBAAoB,MAAM,IAAI,OAAK,EAAE;AACzD,UAAM,mBAAmB,QAAQ,MAAM,MAAM,OAC3C,YAAY,SAAS,EAAE;AAEzB,QAAI,CAAC,kBAAkB;AACrB,YAAM,IAAI,MACR;AAAA;AAAA;AAAA;;;;;;;;;"}

package/dist/index.d.ts

@@ -24,6 +24,20 @@ declare type Permission = {
     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
@@ -52,13 +66,20 @@ declare enum AuthorizeResult {
     CONDITIONAL = "CONDITIONAL"
 }
 /**
- * An authorization request for {@link PermissionClient#authorize}.
+ * An individual authorization request for {@link PermissionClient#authorize}.
  * @public
  */
-declare type AuthorizeRequest = {
+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.
  *
@@ -83,15 +104,22 @@ declare type PermissionCriteria<TQuery> = {
     not: PermissionCriteria<TQuery>;
 } | TQuery;
 /**
- * An authorization response from {@link PermissionClient#authorize}.
+ * An individual authorization response from {@link PermissionClient#authorize}.
  * @public
  */
-declare type AuthorizeResponse = {
+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.
@@ -123,23 +151,16 @@ declare function isUpdatePermission(permission: Permission): boolean;
  */
 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 {
+declare class PermissionClient implements PermissionAuthorizer {
     private readonly enabled;
-    private readonly discoveryApi;
+    private readonly discovery;
     constructor(options: {
-        discoveryApi: DiscoveryApi;
-        configApi: Config;
+        discovery: DiscoveryApi;
+        config: Config;
     });
     /**
      * Request authorization from the permission-backend for the given set of permissions.
@@ -157,9 +178,9 @@ declare class PermissionClient {
      * can be applied when loading collections of resources.
      * @public
      */
-    authorize(requests: AuthorizeRequest[], options?: AuthorizeRequestOptions): Promise<AuthorizeResponse[]>;
+    authorize(queries: AuthorizeQuery[], options?: AuthorizeRequestOptions): Promise<AuthorizeDecision[]>;
     private getAuthorizationHeader;
-    private assertValidResponses;
+    private assertValidResponse;
 }
 
-export { AuthorizeRequest, AuthorizeRequestOptions, AuthorizeResponse, AuthorizeResult, DiscoveryApi, Identified, Permission, PermissionAttributes, PermissionClient, PermissionCondition, PermissionCriteria, isCreatePermission, isDeletePermission, isReadPermission, isUpdatePermission };
+export { AuthorizeDecision, AuthorizeQuery, AuthorizeRequest, AuthorizeRequestOptions, AuthorizeResponse, AuthorizeResult, DiscoveryApi, Identified, Permission, PermissionAttributes, PermissionAuthorizer, PermissionClient, PermissionCondition, PermissionCriteria, isCreatePermission, isDeletePermission, isReadPermission, isUpdatePermission };

package/dist/index.esm.js

@@ -3,12 +3,12 @@ import fetch from 'cross-fetch';
 import * as uuid from 'uuid';
 import { z } from 'zod';
 
-var AuthorizeResult;
-(function(AuthorizeResult2) {
+var AuthorizeResult = /* @__PURE__ */ ((AuthorizeResult2) => {
   AuthorizeResult2["DENY"] = "DENY";
   AuthorizeResult2["ALLOW"] = "ALLOW";
   AuthorizeResult2["CONDITIONAL"] = "CONDITIONAL";
-})(AuthorizeResult || (AuthorizeResult = {}));
+  return AuthorizeResult2;
+})(AuthorizeResult || {});
 
 function isCreatePermission(permission) {
   return permission.attributes.action === "create";
@@ -26,33 +26,37 @@ function isDeletePermission(permission) {
 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
-})));
+}).or(z.object({ anyOf: z.array(permissionCriteriaSchema) })).or(z.object({ allOf: z.array(permissionCriteriaSchema) })).or(z.object({ not: permissionCriteriaSchema })));
+const responseSchema = z.object({
+  items: 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;
+    this.discovery = options.discovery;
+    this.enabled = (_a = options.config.getOptionalBoolean("permission.enabled")) != null ? _a : false;
   }
-  async authorize(requests, options) {
+  async authorize(queries, options) {
     if (!this.enabled) {
-      return requests.map((_) => ({result: AuthorizeResult.ALLOW}));
+      return queries.map((_) => ({ result: AuthorizeResult.ALLOW }));
     }
-    const identifiedRequests = requests.map((request) => ({
-      id: uuid.v4(),
-      ...request
-    }));
-    const permissionApi = await this.discoveryApi.getBaseUrl("permission");
+    const request = {
+      items: queries.map((query) => ({
+        id: uuid.v4(),
+        ...query
+      }))
+    };
+    const permissionApi = await this.discovery.getBaseUrl("permission");
     const response = await fetch(`${permissionApi}/authorize`, {
       method: "POST",
-      body: JSON.stringify(identifiedRequests),
+      body: JSON.stringify(request),
       headers: {
         ...this.getAuthorizationHeader(options == null ? void 0 : options.token),
         "content-type": "application/json"
@@ -61,21 +65,21 @@ class PermissionClient {
     if (!response.ok) {
       throw await ResponseError.fromResponse(response);
     }
-    const identifiedResponses = await response.json();
-    this.assertValidResponses(identifiedRequests, identifiedResponses);
-    const responsesById = identifiedResponses.reduce((acc, r) => {
+    const responseBody = await response.json();
+    this.assertValidResponse(request, responseBody);
+    const responsesById = responseBody.items.reduce((acc, r) => {
       acc[r.id] = r;
       return acc;
     }, {});
-    return identifiedRequests.map((request) => responsesById[request.id]);
+    return request.items.map((query) => responsesById[query.id]);
   }
   getAuthorizationHeader(token) {
-    return token ? {Authorization: `Bearer ${token}`} : {};
+    return token ? { Authorization: `Bearer ${token}` } : {};
   }
-  assertValidResponses(requests, json) {
+  assertValidResponse(request, json) {
     const authorizedResponses = responseSchema.parse(json);
-    const responseIds = authorizedResponses.map((r) => r.id);
-    const hasAllRequestIds = requests.every((r) => responseIds.includes(r.id));
+    const responseIds = authorizedResponses.items.map((r) => r.id);
+    const hasAllRequestIds = request.items.every((r) => responseIds.includes(r.id));
     if (!hasAllRequestIds) {
       throw new Error("Unexpected authorization response from permission-backend");
     }

package/dist/index.esm.js.map

@@ -1 +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;;;;"}
+{"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 individual authorization request for {@link PermissionClient#authorize}.\n * @public\n */\nexport type AuthorizeQuery = {\n  permission: Permission;\n  resourceRef?: string;\n};\n\n/**\n * A batch of authorization requests from {@link PermissionClient#authorize}.\n * @public\n */\nexport type AuthorizeRequest = {\n  items: Identified<AuthorizeQuery>[];\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 individual authorization response from {@link PermissionClient#authorize}.\n * @public\n */\nexport type AuthorizeDecision =\n  | { result: AuthorizeResult.ALLOW | AuthorizeResult.DENY }\n  | {\n      result: AuthorizeResult.CONDITIONAL;\n      conditions: PermissionCriteria<PermissionCondition>;\n    };\n\n/**\n * A batch of authorization responses from {@link PermissionClient#authorize}.\n * @public\n */\nexport type AuthorizeResponse = {\n  items: Identified<AuthorizeDecision>[];\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  AuthorizeQuery,\n  AuthorizeDecision,\n  Identified,\n  PermissionCriteria,\n  PermissionCondition,\n  AuthorizeResponse,\n  AuthorizeRequest,\n} from './types/api';\nimport { DiscoveryApi } from './types/discovery';\nimport {\n  PermissionAuthorizer,\n  AuthorizeRequestOptions,\n} from './types/permission';\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.object({\n  items: 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/**\n * An isomorphic client for requesting authorization for Backstage permissions.\n * @public\n */\nexport class PermissionClient implements PermissionAuthorizer {\n  private readonly enabled: boolean;\n  private readonly discovery: DiscoveryApi;\n\n  constructor(options: { discovery: DiscoveryApi; config: Config }) {\n    this.discovery = options.discovery;\n    this.enabled =\n      options.config.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    queries: AuthorizeQuery[],\n    options?: AuthorizeRequestOptions,\n  ): Promise<AuthorizeDecision[]> {\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 queries.map(_ => ({ result: AuthorizeResult.ALLOW }));\n    }\n\n    const request: AuthorizeRequest = {\n      items: queries.map(query => ({\n        id: uuid.v4(),\n        ...query,\n      })),\n    };\n\n    const permissionApi = await this.discovery.getBaseUrl('permission');\n    const response = await fetch(`${permissionApi}/authorize`, {\n      method: 'POST',\n      body: JSON.stringify(request),\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 responseBody = await response.json();\n    this.assertValidResponse(request, responseBody);\n\n    const responsesById = responseBody.items.reduce((acc, r) => {\n      acc[r.id] = r;\n      return acc;\n    }, {} as Record<string, Identified<AuthorizeDecision>>);\n\n    return request.items.map(query => responsesById[query.id]);\n  }\n\n  private getAuthorizationHeader(token?: string): Record<string, string> {\n    return token ? { Authorization: `Bearer ${token}` } : {};\n  }\n\n  private assertValidResponse(\n    request: AuthorizeRequest,\n    json: any,\n  ): asserts json is AuthorizeResponse {\n    const authorizedResponses = responseSchema.parse(json);\n    const responseIds = authorizedResponses.items.map(r => r.id);\n    const hasAllRequestIds = request.items.every(r =>\n      responseIds.includes(r.id),\n    );\n    if (!hasAllRequestIds) {\n      throw new Error(\n        'Unexpected authorization response from permission-backend',\n      );\n    }\n  }\n}\n"],"names":[],"mappings":";;;;;IA6BY,oCAAA,qBAAL;AAIL,6BAAO;AAIP,8BAAQ;AAIR,oCAAc;AAZJ;AAAA;;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;;ACV1C,MAAM,2BAEF,EAAE,KAAK,MACT,EACG,OAAO;AAAA,EACN,MAAM,EAAE;AAAA,EACR,QAAQ,EAAE,MAAM,EAAE;AAAA,GAEnB,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,8BAC7B,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,8BAC7B,GAAG,EAAE,OAAO,EAAE,KAAK;AAGxB,MAAM,iBAAiB,EAAE,OAAO;AAAA,EAC9B,OAAO,EAAE,MACP,EACG,OAAO;AAAA,IACN,IAAI,EAAE;AAAA,IACN,QAAQ,EACL,QAAQ,gBAAgB,OACxB,GAAG,EAAE,QAAQ,gBAAgB;AAAA,KAEjC,GACC,EAAE,OAAO;AAAA,IACP,IAAI,EAAE;AAAA,IACN,QAAQ,EAAE,QAAQ,gBAAgB;AAAA,IAClC,YAAY;AAAA;AAAA;uBAUwC;AAAA,EAI5D,YAAY,SAAsD;AA7EpE;AA8EI,SAAK,YAAY,QAAQ;AACzB,SAAK,UACH,cAAQ,OAAO,mBAAmB,0BAAlC,YAA2D;AAAA;AAAA,QAmBzD,UACJ,SACA,SAC8B;AAM9B,QAAI,CAAC,KAAK,SAAS;AACjB,aAAO,QAAQ,IAAI,UAAQ,QAAQ,gBAAgB;AAAA;AAGrD,UAAM,UAA4B;AAAA,MAChC,OAAO,QAAQ,IAAI;AAAU,QAC3B,IAAI,KAAK;AAAA,WACN;AAAA;AAAA;AAIP,UAAM,gBAAgB,MAAM,KAAK,UAAU,WAAW;AACtD,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,eAAe,MAAM,SAAS;AACpC,SAAK,oBAAoB,SAAS;AAElC,UAAM,gBAAgB,aAAa,MAAM,OAAO,CAAC,KAAK,MAAM;AAC1D,UAAI,EAAE,MAAM;AACZ,aAAO;AAAA,OACN;AAEH,WAAO,QAAQ,MAAM,IAAI,WAAS,cAAc,MAAM;AAAA;AAAA,EAGhD,uBAAuB,OAAwC;AACrE,WAAO,QAAQ,EAAE,eAAe,UAAU,YAAY;AAAA;AAAA,EAGhD,oBACN,SACA,MACmC;AACnC,UAAM,sBAAsB,eAAe,MAAM;AACjD,UAAM,cAAc,oBAAoB,MAAM,IAAI,OAAK,EAAE;AACzD,UAAM,mBAAmB,QAAQ,MAAM,MAAM,OAC3C,YAAY,SAAS,EAAE;AAEzB,QAAI,CAAC,kBAAkB;AACrB,YAAM,IAAI,MACR;AAAA;AAAA;AAAA;;;;"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/plugin-permission-common",
   "description": "Isomorphic types and client for Backstage permissions and authorization",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "publishConfig": {
@@ -38,17 +38,17 @@
     "url": "https://github.com/backstage/backstage/issues"
   },
   "dependencies": {
-    "@backstage/config": "^0.1.11",
-    "@backstage/errors": "^0.1.5",
+    "@backstage/config": "^0.1.13",
+    "@backstage/errors": "^0.2.0",
     "cross-fetch": "^3.0.6",
     "uuid": "^8.0.0",
     "zod": "^3.11.6"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.9.1",
+    "@backstage/cli": "^0.12.0",
     "@types/jest": "^26.0.7",
     "msw": "^0.35.0"
   },
-  "gitHead": "85c127e436a24140bb3606f17f034f82aa9c7c0d",
+  "gitHead": "600d6e3c854bbfb12a0078ca6f726d1c0d1fea0b",
   "module": "dist/index.esm.js"
 }