@backstage/plugin-permission-node 0.0.0-nightly-2021102522541

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @backstage/plugin-permission-node
+
+## 0.0.0-nightly-2021102522541
+### Minor Changes
+
+- 44b46644d9: New package containing common permission and authorization utilities for backend plugins. For more information, see the [authorization PRFC](https://github.com/backstage/backstage/pull/7761).
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/plugin-auth-backend@0.0.0-nightly-2021102522541
+  - @backstage/plugin-permission-common@0.0.0-nightly-2021102522541

package/README.md

@@ -0,0 +1,7 @@
+# @backstage/plugin-permission-node
+
+> NOTE: THIS PACKAGE IS EXPERIMENTAL, HERE BE DRAGONS
+
+Common permission and authorization utilities for backend plugins. For more
+information, see the [authorization
+PRFC](https://github.com/backstage/backstage/pull/7761).

package/dist/index.cjs.js

@@ -0,0 +1,123 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var express = require('express');
+var zod = require('zod');
+var pluginPermissionCommon = require('@backstage/plugin-permission-common');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+var express__default = /*#__PURE__*/_interopDefaultLegacy(express);
+
+const createConditionFactory = (rule) => (...params) => ({
+  rule: rule.name,
+  params
+});
+
+const createConditionExports = (options) => {
+  const {pluginId, resourceType, rules} = options;
+  return {
+    conditions: Object.entries(rules).reduce((acc, [key, rule]) => ({
+      ...acc,
+      [key]: createConditionFactory(rule)
+    }), {}),
+    createConditions: (conditions) => ({
+      pluginId,
+      resourceType,
+      conditions
+    })
+  };
+};
+
+const isAndCriteria = (filter) => Object.prototype.hasOwnProperty.call(filter, "allOf");
+const isOrCriteria = (filter) => Object.prototype.hasOwnProperty.call(filter, "anyOf");
+const isNotCriteria = (filter) => Object.prototype.hasOwnProperty.call(filter, "not");
+const createGetRule = (rules) => {
+  const rulesMap = new Map(Object.values(rules).map((rule) => [rule.name, rule]));
+  return (name) => {
+    const rule = rulesMap.get(name);
+    if (!rule) {
+      throw new Error(`Unexpected permission rule: ${name}`);
+    }
+    return rule;
+  };
+};
+
+const mapConditions = (criteria, getRule) => {
+  if (isAndCriteria(criteria)) {
+    return {
+      allOf: criteria.allOf.map((child) => mapConditions(child, getRule))
+    };
+  } else if (isOrCriteria(criteria)) {
+    return {
+      anyOf: criteria.anyOf.map((child) => mapConditions(child, getRule))
+    };
+  } else if (isNotCriteria(criteria)) {
+    return {
+      not: mapConditions(criteria.not, getRule)
+    };
+  }
+  return getRule(criteria.rule).toQuery(...criteria.params);
+};
+const createConditionTransformer = (permissionRules) => {
+  const getRule = createGetRule(permissionRules);
+  return (conditions) => mapConditions(conditions, getRule);
+};
+
+const permissionCriteriaSchema = zod.z.lazy(() => zod.z.union([
+  zod.z.object({anyOf: zod.z.array(permissionCriteriaSchema)}),
+  zod.z.object({allOf: zod.z.array(permissionCriteriaSchema)}),
+  zod.z.object({not: permissionCriteriaSchema}),
+  zod.z.object({
+    rule: zod.z.string(),
+    params: zod.z.array(zod.z.unknown())
+  })
+]));
+const applyConditionsRequestSchema = zod.z.object({
+  resourceRef: zod.z.string(),
+  resourceType: zod.z.string(),
+  conditions: permissionCriteriaSchema
+});
+const applyConditions = (criteria, resource, getRule) => {
+  if (isAndCriteria(criteria)) {
+    return criteria.allOf.every((child) => applyConditions(child, resource, getRule));
+  } else if (isOrCriteria(criteria)) {
+    return criteria.anyOf.some((child) => applyConditions(child, resource, getRule));
+  } else if (isNotCriteria(criteria)) {
+    return !applyConditions(criteria.not, resource, getRule);
+  }
+  return getRule(criteria.rule).apply(resource, ...criteria.params);
+};
+const createPermissionIntegrationRouter = ({
+  resourceType,
+  rules,
+  getResource
+}) => {
+  const router = express.Router();
+  const getRule = createGetRule(rules);
+  router.post("/permissions/apply-conditions", express__default['default'].json(), async (req, res) => {
+    const parseResult = applyConditionsRequestSchema.safeParse(req.body);
+    if (!parseResult.success) {
+      return res.status(400).send(`Invalid request body.`);
+    }
+    const {data: body} = parseResult;
+    if (body.resourceType !== resourceType) {
+      return res.status(400).send(`Unexpected resource type: ${body.resourceType}.`);
+    }
+    const resource = await getResource(body.resourceRef);
+    if (!resource) {
+      return res.status(400).send(`Resource for ref ${body.resourceRef} not found.`);
+    }
+    return res.status(200).json({
+      result: applyConditions(body.conditions, resource, getRule) ? pluginPermissionCommon.AuthorizeResult.ALLOW : pluginPermissionCommon.AuthorizeResult.DENY
+    });
+  });
+  return router;
+};
+
+exports.createConditionExports = createConditionExports;
+exports.createConditionFactory = createConditionFactory;
+exports.createConditionTransformer = createConditionTransformer;
+exports.createPermissionIntegrationRouter = createPermissionIntegrationRouter;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs.js","sources":["../src/integration/createConditionFactory.ts","../src/integration/createConditionExports.ts","../src/integration/util.ts","../src/integration/createConditionTransformer.ts","../src/integration/createPermissionIntegrationRouter.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 { PermissionRule } from '../types';\n\n/**\n * Creates a condition factory function for a given authorization rule and parameter types.\n *\n * @remarks\n *\n * For example, an isEntityOwner rule for catalog entities might take an array of entityRef strings.\n * The rule itself defines _how_ to check a given resource, whereas a condition also includes _what_\n * to verify.\n *\n * Plugin authors should generally use the {@link createConditionExports} in order to efficiently\n * create multiple condition factories. This helper should generally only be used to construct\n * condition factories for third-party rules that aren't part of the backend plugin with which\n * they're intended to integrate.\n *\n * @public\n */\nexport const createConditionFactory =\n  <TParams extends any[]>(rule: PermissionRule<unknown, unknown, TParams>) =>\n  (...params: TParams) => ({\n    rule: rule.name,\n    params,\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 {\n  PermissionCondition,\n  PermissionCriteria,\n} from '@backstage/plugin-permission-common';\nimport { PermissionRule } from '../types';\nimport { createConditionFactory } from './createConditionFactory';\n\n/**\n * A utility type for mapping a single {@link PermissionRule} to its\n * corresponding {@link @backstage/plugin-permission-common#PermissionCondition}.\n *\n * @public\n */\nexport type Condition<TRule> = TRule extends PermissionRule<\n  any,\n  any,\n  infer TParams\n>\n  ? (...params: TParams) => PermissionCondition<TParams>\n  : never;\n\n/**\n * A utility type for mapping {@link PermissionRule}s to their corresponding\n * {@link @backstage/plugin-permission-common#PermissionCondition}s.\n *\n * @public\n */\nexport type Conditions<\n  TRules extends Record<string, PermissionRule<any, any>>,\n> = {\n  [Name in keyof TRules]: Condition<TRules[Name]>;\n};\n\n/**\n * Creates the recommended condition-related exports for a given plugin based on the built-in\n * {@link PermissionRule}s it supports.\n *\n * @remarks\n *\n * The function returns a `conditions` object containing a\n * {@link @backstage/plugin-permission-common#PermissionCondition} factory for each of the\n * supplied {@link PermissionRule}s, along with a `createConditions` function which builds the\n * wrapper object needed to enclose conditions when authoring {@link PermissionPolicy} implementations.\n *\n * Plugin authors should generally call this method with all the built-in {@link PermissionRule}s\n * the plugin supports, and export the resulting `conditions` object and `createConditions`\n * function so that they can be used by {@link PermissionPolicy} authors.\n *\n * @public\n */\nexport const createConditionExports = <\n  TResource,\n  TRules extends Record<string, PermissionRule<TResource, any>>,\n>(options: {\n  pluginId: string;\n  resourceType: string;\n  rules: TRules;\n}): {\n  conditions: Conditions<TRules>;\n  createConditions: (conditions: PermissionCriteria<PermissionCondition>) => {\n    pluginId: string;\n    resourceType: string;\n    conditions: PermissionCriteria<PermissionCondition>;\n  };\n} => {\n  const { pluginId, resourceType, rules } = options;\n\n  return {\n    conditions: Object.entries(rules).reduce(\n      (acc, [key, rule]) => ({\n        ...acc,\n        [key]: createConditionFactory(rule),\n      }),\n      {} as Conditions<TRules>,\n    ),\n    createConditions: (\n      conditions: PermissionCriteria<PermissionCondition>,\n    ) => ({\n      pluginId,\n      resourceType,\n      conditions,\n    }),\n  };\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 { PermissionCriteria } from '@backstage/plugin-permission-common';\nimport { PermissionRule } from '../types';\n\nexport const isAndCriteria = (\n  filter: PermissionCriteria<unknown>,\n): filter is { allOf: PermissionCriteria<unknown>[] } =>\n  Object.prototype.hasOwnProperty.call(filter, 'allOf');\n\nexport const isOrCriteria = (\n  filter: PermissionCriteria<unknown>,\n): filter is { anyOf: PermissionCriteria<unknown>[] } =>\n  Object.prototype.hasOwnProperty.call(filter, 'anyOf');\n\nexport const isNotCriteria = (\n  filter: PermissionCriteria<unknown>,\n): filter is { not: PermissionCriteria<unknown> } =>\n  Object.prototype.hasOwnProperty.call(filter, 'not');\n\nexport const createGetRule = <TResource, TQuery>(\n  rules: PermissionRule<TResource, TQuery>[],\n) => {\n  const rulesMap = new Map(Object.values(rules).map(rule => [rule.name, rule]));\n\n  return (name: string): PermissionRule<TResource, TQuery> => {\n    const rule = rulesMap.get(name);\n\n    if (!rule) {\n      throw new Error(`Unexpected permission rule: ${name}`);\n    }\n\n    return rule;\n  };\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 */\nimport {\n  PermissionCondition,\n  PermissionCriteria,\n} from '@backstage/plugin-permission-common';\nimport { PermissionRule } from '../types';\nimport {\n  createGetRule,\n  isAndCriteria,\n  isNotCriteria,\n  isOrCriteria,\n} from './util';\n\nconst mapConditions = <TQuery>(\n  criteria: PermissionCriteria<PermissionCondition>,\n  getRule: (name: string) => PermissionRule<unknown, TQuery>,\n): PermissionCriteria<TQuery> => {\n  if (isAndCriteria(criteria)) {\n    return {\n      allOf: criteria.allOf.map(child => mapConditions(child, getRule)),\n    };\n  } else if (isOrCriteria(criteria)) {\n    return {\n      anyOf: criteria.anyOf.map(child => mapConditions(child, getRule)),\n    };\n  } else if (isNotCriteria(criteria)) {\n    return {\n      not: mapConditions(criteria.not, getRule),\n    };\n  }\n\n  return getRule(criteria.rule).toQuery(...criteria.params);\n};\n\n/**\n * A function which accepts {@link @backstage/plugin-permission-common#PermissionCondition}s\n * logically grouped in a {@link @backstage/plugin-permission-common#PermissionCriteria}\n * object, and transforms the {@link @backstage/plugin-permission-common#PermissionCondition}s\n * into plugin specific query fragments while retaining the enclosing criteria shape.\n *\n * @public\n */\nexport type ConditionTransformer<TQuery> = (\n  conditions: PermissionCriteria<PermissionCondition>,\n) => PermissionCriteria<TQuery>;\n\n/**\n * A higher-order helper function which accepts an array of\n * {@link PermissionRule}s, and returns a {@link ConditionTransformer}\n * which transforms input conditions into equivalent plugin-specific\n * query fragments using the supplied rules.\n *\n * @public\n */\nexport const createConditionTransformer = <\n  TQuery,\n  TRules extends PermissionRule<any, TQuery>[],\n>(\n  permissionRules: [...TRules],\n): ConditionTransformer<TQuery> => {\n  const getRule = createGetRule(permissionRules);\n\n  return conditions => mapConditions(conditions, getRule);\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 express, { Response, Router } from 'express';\nimport { z } from 'zod';\nimport {\n  AuthorizeResult,\n  PermissionCondition,\n  PermissionCriteria,\n} from '@backstage/plugin-permission-common';\nimport { PermissionRule } from '../types';\nimport {\n  createGetRule,\n  isAndCriteria,\n  isNotCriteria,\n  isOrCriteria,\n} from './util';\n\nconst permissionCriteriaSchema: z.ZodSchema<\n  PermissionCriteria<PermissionCondition>\n> = z.lazy(() =>\n  z.union([\n    z.object({ anyOf: z.array(permissionCriteriaSchema) }),\n    z.object({ allOf: z.array(permissionCriteriaSchema) }),\n    z.object({ not: permissionCriteriaSchema }),\n    z.object({\n      rule: z.string(),\n      params: z.array(z.unknown()),\n    }),\n  ]),\n);\n\nconst applyConditionsRequestSchema = z.object({\n  resourceRef: z.string(),\n  resourceType: z.string(),\n  conditions: permissionCriteriaSchema,\n});\n\n/**\n * A request to load the referenced resource and apply conditions in order to\n * finalize a conditional authorization response.\n *\n * @public\n */\nexport type ApplyConditionsRequest = {\n  resourceRef: string;\n  resourceType: string;\n  conditions: PermissionCriteria<PermissionCondition>;\n};\n\n/**\n * The result of applying the conditions, expressed as a definitive authorize\n * result of ALLOW or DENY.\n *\n * @public\n */\nexport type ApplyConditionsResponse = {\n  result: AuthorizeResult.ALLOW | AuthorizeResult.DENY;\n};\n\nconst applyConditions = <TResource>(\n  criteria: PermissionCriteria<PermissionCondition>,\n  resource: TResource,\n  getRule: (name: string) => PermissionRule<TResource, unknown>,\n): boolean => {\n  if (isAndCriteria(criteria)) {\n    return criteria.allOf.every(child =>\n      applyConditions(child, resource, getRule),\n    );\n  } else if (isOrCriteria(criteria)) {\n    return criteria.anyOf.some(child =>\n      applyConditions(child, resource, getRule),\n    );\n  } else if (isNotCriteria(criteria)) {\n    return !applyConditions(criteria.not, resource, getRule);\n  }\n\n  return getRule(criteria.rule).apply(resource, ...criteria.params);\n};\n\n/**\n * Create an express Router which provides an authorization route to allow integration between the\n * permission backend and other Backstage backend plugins. Plugin owners that wish to support\n * conditional authorization for their resources should add the router created by this function\n * to their express app inside their `createRouter` implementation.\n *\n * @remarks\n *\n * To make this concrete, we can use the Backstage software catalog as an example. The catalog has\n * conditional rules around access to specific _entities_ in the catalog. The _type_ of resource is\n * captured here as `resourceType`, a string identifier (`catalog-entity` in this example) that can\n * be provided with permission definitions. This is merely a _type_ to verify that conditions in an\n * authorization policy are constructed correctly, not a reference to a specific resource.\n *\n * The `rules` parameter is an array of {@link PermissionRule}s that introduce conditional\n * filtering logic for resources; for the catalog, these are things like `isEntityOwner` or\n * `hasAnnotation`. Rules describe how to filter a list of resources, and the `conditions` returned\n * allow these rules to be applied with specific parameters (such as 'group:default/team-a', or\n * 'backstage.io/edit-url').\n *\n * The `getResource` argument should load a resource by reference. For the catalog, this is an\n * {@link @backstage/catalog-model#EntityRef}. For other plugins, this can be any serialized format.\n * This is used to construct the `createPermissionIntegrationRouter`, a function to add an\n * authorization route to your backend plugin. This route will be called by the `permission-backend`\n * when authorization conditions relating to this plugin need to be evaluated.\n * @public\n */\nexport const createPermissionIntegrationRouter = <TResource>({\n  resourceType,\n  rules,\n  getResource,\n}: {\n  resourceType: string;\n  rules: PermissionRule<TResource, any>[];\n  getResource: (resourceRef: string) => Promise<TResource | undefined>;\n}): Router => {\n  const router = Router();\n\n  const getRule = createGetRule(rules);\n\n  router.post(\n    '/permissions/apply-conditions',\n    express.json(),\n    async (\n      req,\n      res: Response<\n        | {\n            result: Omit<AuthorizeResult, AuthorizeResult.CONDITIONAL>;\n          }\n        | string\n      >,\n    ) => {\n      const parseResult = applyConditionsRequestSchema.safeParse(req.body);\n\n      if (!parseResult.success) {\n        return res.status(400).send(`Invalid request body.`);\n      }\n\n      const { data: body } = parseResult;\n\n      if (body.resourceType !== resourceType) {\n        return res\n          .status(400)\n          .send(`Unexpected resource type: ${body.resourceType}.`);\n      }\n\n      const resource = await getResource(body.resourceRef);\n\n      if (!resource) {\n        return res\n          .status(400)\n          .send(`Resource for ref ${body.resourceRef} not found.`);\n      }\n\n      return res.status(200).json({\n        result: applyConditions(body.conditions, resource, getRule)\n          ? AuthorizeResult.ALLOW\n          : AuthorizeResult.DENY,\n      });\n    },\n  );\n\n  return router;\n};\n"],"names":["z","Router","express","AuthorizeResult"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,238 @@
+import { PermissionCriteria, PermissionCondition, AuthorizeResult, AuthorizeRequest } from '@backstage/plugin-permission-common';
+import { Router } from 'express';
+import { BackstageIdentity } from '@backstage/plugin-auth-backend';
+
+/**
+ * A conditional rule that can be provided in an
+ * {@link @backstage/permission-common#AuthorizeResult} response to an authorization request.
+ *
+ * @remarks
+ *
+ * Rules can either be evaluated against a resource loaded in memory, or used as filters when
+ * loading a collection of resources from a data source. The `apply` and `toQuery` methods implement
+ * these two concepts.
+ *
+ * The two operations should always have the same logical result. If they don’t, the effective
+ * outcome of an authorization operation will sometimes differ depending on how the authorization
+ * check was performed.
+ *
+ * @public
+ */
+declare type PermissionRule<TResource, TQuery, TParams extends unknown[] = unknown[]> = {
+    name: string;
+    description: string;
+    /**
+     * Apply this rule to a resource already loaded from a backing data source. The params are
+     * arguments supplied for the rule; for example, a rule could be `isOwner` with entityRefs as the
+     * params.
+     */
+    apply(resource: TResource, ...params: TParams): boolean;
+    /**
+     * Translate this rule to criteria suitable for use in querying a backing data store. The criteria
+     * can be used for loading a collection of resources efficiently with conditional criteria already
+     * applied.
+     */
+    toQuery(...params: TParams): PermissionCriteria<TQuery>;
+};
+
+/**
+ * Creates a condition factory function for a given authorization rule and parameter types.
+ *
+ * @remarks
+ *
+ * For example, an isEntityOwner rule for catalog entities might take an array of entityRef strings.
+ * The rule itself defines _how_ to check a given resource, whereas a condition also includes _what_
+ * to verify.
+ *
+ * Plugin authors should generally use the {@link createConditionExports} in order to efficiently
+ * create multiple condition factories. This helper should generally only be used to construct
+ * condition factories for third-party rules that aren't part of the backend plugin with which
+ * they're intended to integrate.
+ *
+ * @public
+ */
+declare const createConditionFactory: <TParams extends any[]>(rule: PermissionRule<unknown, unknown, TParams>) => (...params: TParams) => {
+    rule: string;
+    params: TParams;
+};
+
+/**
+ * A utility type for mapping a single {@link PermissionRule} to its
+ * corresponding {@link @backstage/plugin-permission-common#PermissionCondition}.
+ *
+ * @public
+ */
+declare type Condition<TRule> = TRule extends PermissionRule<any, any, infer TParams> ? (...params: TParams) => PermissionCondition<TParams> : never;
+/**
+ * A utility type for mapping {@link PermissionRule}s to their corresponding
+ * {@link @backstage/plugin-permission-common#PermissionCondition}s.
+ *
+ * @public
+ */
+declare type Conditions<TRules extends Record<string, PermissionRule<any, any>>> = {
+    [Name in keyof TRules]: Condition<TRules[Name]>;
+};
+/**
+ * Creates the recommended condition-related exports for a given plugin based on the built-in
+ * {@link PermissionRule}s it supports.
+ *
+ * @remarks
+ *
+ * The function returns a `conditions` object containing a
+ * {@link @backstage/plugin-permission-common#PermissionCondition} factory for each of the
+ * supplied {@link PermissionRule}s, along with a `createConditions` function which builds the
+ * wrapper object needed to enclose conditions when authoring {@link PermissionPolicy} implementations.
+ *
+ * Plugin authors should generally call this method with all the built-in {@link PermissionRule}s
+ * the plugin supports, and export the resulting `conditions` object and `createConditions`
+ * function so that they can be used by {@link PermissionPolicy} authors.
+ *
+ * @public
+ */
+declare const createConditionExports: <TResource, TRules extends Record<string, PermissionRule<TResource, any, unknown[]>>>(options: {
+    pluginId: string;
+    resourceType: string;
+    rules: TRules;
+}) => {
+    conditions: Conditions<TRules>;
+    createConditions: (conditions: PermissionCriteria<PermissionCondition>) => {
+        pluginId: string;
+        resourceType: string;
+        conditions: PermissionCriteria<PermissionCondition>;
+    };
+};
+
+/**
+ * A function which accepts {@link @backstage/plugin-permission-common#PermissionCondition}s
+ * logically grouped in a {@link @backstage/plugin-permission-common#PermissionCriteria}
+ * object, and transforms the {@link @backstage/plugin-permission-common#PermissionCondition}s
+ * into plugin specific query fragments while retaining the enclosing criteria shape.
+ *
+ * @public
+ */
+declare type ConditionTransformer<TQuery> = (conditions: PermissionCriteria<PermissionCondition>) => PermissionCriteria<TQuery>;
+/**
+ * A higher-order helper function which accepts an array of
+ * {@link PermissionRule}s, and returns a {@link ConditionTransformer}
+ * which transforms input conditions into equivalent plugin-specific
+ * query fragments using the supplied rules.
+ *
+ * @public
+ */
+declare const createConditionTransformer: <TQuery, TRules extends PermissionRule<any, TQuery, unknown[]>[]>(permissionRules: [...TRules]) => ConditionTransformer<TQuery>;
+
+/**
+ * A request to load the referenced resource and apply conditions in order to
+ * finalize a conditional authorization response.
+ *
+ * @public
+ */
+declare type ApplyConditionsRequest = {
+    resourceRef: string;
+    resourceType: string;
+    conditions: PermissionCriteria<PermissionCondition>;
+};
+/**
+ * The result of applying the conditions, expressed as a definitive authorize
+ * result of ALLOW or DENY.
+ *
+ * @public
+ */
+declare type ApplyConditionsResponse = {
+    result: AuthorizeResult.ALLOW | AuthorizeResult.DENY;
+};
+/**
+ * Create an express Router which provides an authorization route to allow integration between the
+ * permission backend and other Backstage backend plugins. Plugin owners that wish to support
+ * conditional authorization for their resources should add the router created by this function
+ * to their express app inside their `createRouter` implementation.
+ *
+ * @remarks
+ *
+ * To make this concrete, we can use the Backstage software catalog as an example. The catalog has
+ * conditional rules around access to specific _entities_ in the catalog. The _type_ of resource is
+ * captured here as `resourceType`, a string identifier (`catalog-entity` in this example) that can
+ * be provided with permission definitions. This is merely a _type_ to verify that conditions in an
+ * authorization policy are constructed correctly, not a reference to a specific resource.
+ *
+ * The `rules` parameter is an array of {@link PermissionRule}s that introduce conditional
+ * filtering logic for resources; for the catalog, these are things like `isEntityOwner` or
+ * `hasAnnotation`. Rules describe how to filter a list of resources, and the `conditions` returned
+ * allow these rules to be applied with specific parameters (such as 'group:default/team-a', or
+ * 'backstage.io/edit-url').
+ *
+ * The `getResource` argument should load a resource by reference. For the catalog, this is an
+ * {@link @backstage/catalog-model#EntityRef}. For other plugins, this can be any serialized format.
+ * This is used to construct the `createPermissionIntegrationRouter`, a function to add an
+ * authorization route to your backend plugin. This route will be called by the `permission-backend`
+ * when authorization conditions relating to this plugin need to be evaluated.
+ * @public
+ */
+declare const createPermissionIntegrationRouter: <TResource>({ resourceType, rules, getResource, }: {
+    resourceType: string;
+    rules: PermissionRule<TResource, any, unknown[]>[];
+    getResource: (resourceRef: string) => Promise<TResource | undefined>;
+}) => Router;
+
+/**
+ * An authorization request to be evaluated by the {@link PermissionPolicy}.
+ *
+ * @remarks
+ *
+ * This differs from {@link @backstage/permission-common#AuthorizeRequest} in that `resourceRef`
+ * should never be provided. This forces policies to be written in a way that's compatible with
+ * filtering collections of resources at data load time.
+ *
+ * @public
+ */
+declare type PolicyAuthorizeRequest = Omit<AuthorizeRequest, 'resourceRef'>;
+/**
+ * A conditional result to an authorization request, returned by the {@link PermissionPolicy}.
+ *
+ * @remarks
+ *
+ * This indicates that the policy allows authorization for the request, given that the returned
+ * conditions hold when evaluated. The conditions will be evaluated by the corresponding plugin
+ * which knows about the referenced permission rules.
+ *
+ * Similar to {@link @backstage/permission-common#AuthorizeResult}, but with the plugin and resource
+ * identifiers needed to evaluate the returned conditions.
+ * @public
+ */
+declare type ConditionalPolicyResult = {
+    result: AuthorizeResult.CONDITIONAL;
+    conditions: {
+        pluginId: string;
+        resourceType: string;
+        conditions: PermissionCriteria<PermissionCondition>;
+    };
+};
+/**
+ * The result of evaluating an authorization request with a {@link PermissionPolicy}.
+ *
+ * @public
+ */
+declare type PolicyResult = {
+    result: AuthorizeResult.ALLOW | AuthorizeResult.DENY;
+} | ConditionalPolicyResult;
+/**
+ * A policy to evaluate authorization requests for any permissioned action performed in Backstage.
+ *
+ * @remarks
+ *
+ * This takes as input a permission and an optional Backstage identity, and should return ALLOW if
+ * the user is permitted to execute that action; otherwise DENY. For permissions relating to
+ * resources, such a catalog entities, a conditional response can also be returned. This states
+ * that the action is allowed if the conditions provided hold true.
+ *
+ * Conditions are a rule, and parameters to evaluate against that rule. For example, the rule might
+ * be `isOwner` and the parameters a collection of entityRefs; if one of the entityRefs matches
+ * the `owner` field on a catalog entity, this would resolve to ALLOW.
+ *
+ * @public
+ */
+interface PermissionPolicy {
+    handle(request: PolicyAuthorizeRequest, user?: BackstageIdentity): Promise<PolicyResult>;
+}
+
+export { ApplyConditionsRequest, ApplyConditionsResponse, Condition, ConditionTransformer, ConditionalPolicyResult, Conditions, PermissionPolicy, PermissionRule, PolicyAuthorizeRequest, PolicyResult, createConditionExports, createConditionFactory, createConditionTransformer, createPermissionIntegrationRouter };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@backstage/plugin-permission-node",
+  "description": "Common permission and authorization utilities for backend plugins",
+  "version": "0.0.0-nightly-2021102522541",
+  "main": "dist/index.cjs.js",
+  "types": "dist/index.d.ts",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts"
+  },
+  "homepage": "https://backstage.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/backstage/backstage",
+    "directory": "plugins/permission-node"
+  },
+  "keywords": [
+    "backstage",
+    "permissions"
+  ],
+  "scripts": {
+    "build": "backstage-cli backend:build",
+    "lint": "backstage-cli lint",
+    "test": "backstage-cli test",
+    "prepack": "backstage-cli prepack",
+    "postpack": "backstage-cli postpack",
+    "clean": "backstage-cli clean"
+  },
+  "dependencies": {
+    "@backstage/plugin-auth-backend": "^0.0.0-nightly-2021102522541",
+    "@backstage/plugin-permission-common": "^0.0.0-nightly-2021102522541",
+    "@types/express": "^4.17.6",
+    "express": "^4.17.1",
+    "zod": "^3.11.6"
+  },
+  "devDependencies": {
+    "@backstage/cli": "^0.0.0-nightly-2021102522541",
+    "@types/supertest": "^2.0.8",
+    "supertest": "^6.1.3"
+  },
+  "files": [
+    "dist"
+  ]
+}