@backstage/plugin-permission-node 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @backstage/plugin-permission-node
 
+## 0.2.1
+
+### Patch Changes
+
+- dcd1a0c3f4: Minor improvement to the API reports, by not unpacking arguments directly
+- a036b65c2f: Updated to use the new `BackstageIdentityResponse` type from `@backstage/plugin-auth-backend`.
+
+  The `BackstageIdentityResponse` type is backwards compatible with the `BackstageIdentity`, and provides an additional `identity` field with the claims of the user.
+
+- Updated dependencies
+  - @backstage/plugin-auth-backend@0.5.0
+
 ## 0.2.0
 
 ### Minor Changes

package/dist/index.cjs.js

@@ -16,7 +16,7 @@ const createConditionFactory = (rule) => (...params) => ({
 });
 
 const createConditionExports = (options) => {
-  const {pluginId, resourceType, rules} = options;
+  const { pluginId, resourceType, rules } = options;
   return {
     conditions: Object.entries(rules).reduce((acc, [key, rule]) => ({
       ...acc,
@@ -67,9 +67,9 @@ const createConditionTransformer = (permissionRules) => {
 };
 
 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({ 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())
@@ -90,19 +90,16 @@ const applyConditions = (criteria, resource, getRule) => {
   }
   return getRule(criteria.rule).apply(resource, ...criteria.params);
 };
-const createPermissionIntegrationRouter = ({
-  resourceType,
-  rules,
-  getResource
-}) => {
+const createPermissionIntegrationRouter = (options) => {
+  const { resourceType, rules, getResource } = options;
   const router = express.Router();
   const getRule = createGetRule(rules);
-  router.post("/.well-known/backstage/permissions/apply-conditions", express__default['default'].json(), async (req, res) => {
+  router.post("/.well-known/backstage/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;
+    const { data: body } = parseResult;
     if (body.resourceType !== resourceType) {
       return res.status(400).send(`Unexpected resource type: ${body.resourceType}.`);
     }

package/dist/index.cjs.js.map

@@ -1 +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  AuthorizeResult,\n  PermissionCondition,\n  PermissionCriteria,\n} from '@backstage/plugin-permission-common';\nimport { ConditionalPolicyDecision } from '../policy';\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  createPolicyDecision: (\n    conditions: PermissionCriteria<PermissionCondition>,\n  ) => ConditionalPolicyDecision;\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    createPolicyDecision: (\n      conditions: PermissionCriteria<PermissionCondition>,\n    ) => ({\n      result: AuthorizeResult.CONDITIONAL,\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    '/.well-known/backstage/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":["AuthorizeResult","z","Router","express"],"mappings":"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"}
+{"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  AuthorizeResult,\n  PermissionCondition,\n  PermissionCriteria,\n} from '@backstage/plugin-permission-common';\nimport { ConditionalPolicyDecision } from '../policy';\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  createPolicyDecision: (\n    conditions: PermissionCriteria<PermissionCondition>,\n  ) => ConditionalPolicyDecision;\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    createPolicyDecision: (\n      conditions: PermissionCriteria<PermissionCondition>,\n    ) => ({\n      result: AuthorizeResult.CONDITIONAL,\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 *\n * @public\n */\nexport const createPermissionIntegrationRouter = <TResource>(options: {\n  resourceType: string;\n  rules: PermissionRule<TResource, any>[];\n  getResource: (resourceRef: string) => Promise<TResource | undefined>;\n}): Router => {\n  const { resourceType, rules, getResource } = options;\n  const router = Router();\n\n  const getRule = createGetRule(rules);\n\n  router.post(\n    '/.well-known/backstage/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":["AuthorizeResult","z","Router","express"],"mappings":"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"}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { PermissionCriteria, AuthorizeRequest, AuthorizeResult, PermissionCondition } from '@backstage/plugin-permission-common';
-import { BackstageIdentity } from '@backstage/plugin-auth-backend';
+import { BackstageIdentityResponse } from '@backstage/plugin-auth-backend';
 import { Router } from 'express';
 
 /**
@@ -112,7 +112,7 @@ declare type PolicyDecision = {
  * @public
  */
 interface PermissionPolicy {
-    handle(request: PolicyAuthorizeRequest, user?: BackstageIdentity): Promise<PolicyDecision>;
+    handle(request: PolicyAuthorizeRequest, user?: BackstageIdentityResponse): Promise<PolicyDecision>;
 }
 
 /**
@@ -221,9 +221,10 @@ declare type ApplyConditionsResponse = {
  * 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, }: {
+declare const createPermissionIntegrationRouter: <TResource>(options: {
     resourceType: string;
     rules: PermissionRule<TResource, any, unknown[]>[];
     getResource: (resourceRef: string) => Promise<TResource | undefined>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/plugin-permission-node",
   "description": "Common permission and authorization utilities for backend plugins",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "license": "Apache-2.0",
@@ -29,19 +29,19 @@
     "clean": "backstage-cli clean"
   },
   "dependencies": {
-    "@backstage/plugin-auth-backend": "^0.4.10",
+    "@backstage/plugin-auth-backend": "^0.5.0",
     "@backstage/plugin-permission-common": "^0.2.0",
     "@types/express": "^4.17.6",
     "express": "^4.17.1",
     "zod": "^3.11.6"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.10.0",
+    "@backstage/cli": "^0.10.1",
     "@types/supertest": "^2.0.8",
     "supertest": "^6.1.3"
   },
   "files": [
     "dist"
   ],
-  "gitHead": "a05e7081b805006e3f0b2960a08a7753357f532f"
+  "gitHead": "562be0b43016294e27af3ad024191bb86b13b1c1"
 }