@backstage/plugin-permission-node 0.5.0 → 0.5.1

package/CHANGELOG.md

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

package/dist/index.d.ts

@@ -0,0 +1,301 @@
+import { PermissionCriteria, AuthorizeQuery, AuthorizeResult, PermissionCondition, Identified, PermissionAuthorizer, AuthorizeRequestOptions, AuthorizeDecision } from '@backstage/plugin-permission-common';
+import { BackstageIdentityResponse } from '@backstage/plugin-auth-node';
+import express from 'express';
+import { PluginEndpointDiscovery, TokenManager } from '@backstage/backend-common';
+import { Config } from '@backstage/config';
+
+/**
+ * A conditional rule that can be provided in an
+ * {@link @backstage/permission-common#AuthorizeDecision} 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;
+};
+
+/**
+ * An authorization request to be evaluated by the {@link PermissionPolicy}.
+ *
+ * @remarks
+ *
+ * This differs from {@link @backstage/permission-common#AuthorizeQuery} 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 PolicyAuthorizeQuery = Omit<AuthorizeQuery, 'resourceRef'>;
+/**
+ * A definitive result to an authorization request, returned by the {@link PermissionPolicy}.
+ *
+ * @remarks
+ *
+ * This indicates that the policy unconditionally allows (or denies) the request.
+ *
+ * @public
+ */
+declare type DefinitivePolicyDecision = {
+    result: AuthorizeResult.ALLOW | AuthorizeResult.DENY;
+};
+/**
+ * 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#AuthorizeDecision}, but with the plugin and resource
+ * identifiers needed to evaluate the returned conditions.
+ * @public
+ */
+declare type ConditionalPolicyDecision = {
+    result: AuthorizeResult.CONDITIONAL;
+    pluginId: string;
+    resourceType: string;
+    conditions: PermissionCriteria<PermissionCondition>;
+};
+/**
+ * The result of evaluating an authorization request with a {@link PermissionPolicy}.
+ *
+ * @public
+ */
+declare type PolicyDecision = DefinitivePolicyDecision | ConditionalPolicyDecision;
+/**
+ * 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: PolicyAuthorizeQuery, user?: BackstageIdentityResponse): Promise<PolicyDecision>;
+}
+
+/**
+ * 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>;
+    createPolicyDecision: (conditions: PermissionCriteria<PermissionCondition>) => ConditionalPolicyDecision;
+};
+
+/**
+ * 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 ApplyConditionsRequestEntry = Identified<{
+    resourceRef: string;
+    resourceType: string;
+    conditions: PermissionCriteria<PermissionCondition>;
+}>;
+/**
+ * A batch of {@link ApplyConditionsRequestEntry} objects.
+ *
+ * @public
+ */
+declare type ApplyConditionsRequest = {
+    items: ApplyConditionsRequestEntry[];
+};
+/**
+ * The result of applying the conditions, expressed as a definitive authorize
+ * result of ALLOW or DENY.
+ *
+ * @public
+ */
+declare type ApplyConditionsResponseEntry = Identified<DefinitivePolicyDecision>;
+/**
+ * A batch of {@link ApplyConditionsResponseEntry} objects.
+ *
+ * @public
+ */
+declare type ApplyConditionsResponse = {
+    items: ApplyConditionsResponseEntry[];
+};
+/**
+ * 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 `getResources` argument should load resources based on a reference
+ * identifier. 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 function will be called by the
+ * `permission-backend` when authorization conditions relating to this plugin
+ * need to be evaluated.
+ *
+ * @public
+ */
+declare const createPermissionIntegrationRouter: <TResource>(options: {
+    resourceType: string;
+    rules: PermissionRule<TResource, any, unknown[]>[];
+    getResources: (resourceRefs: string[]) => Promise<(TResource | undefined)[]>;
+}) => express.Router;
+
+/**
+ * Helper function to ensure that {@link PermissionRule} definitions are typed correctly.
+ *
+ * @public
+ */
+declare const createPermissionRule: <TResource, TQuery, TParams extends unknown[]>(rule: PermissionRule<TResource, TQuery, TParams>) => PermissionRule<TResource, TQuery, TParams>;
+/**
+ * Helper for making plugin-specific createPermissionRule functions, that have
+ * the TResource and TQuery type parameters populated but infer the params from
+ * the supplied rule. This helps ensure that rules created for this plugin use
+ * consistent types for the resource and query.
+ *
+ * @public
+ */
+declare const makeCreatePermissionRule: <TResource, TQuery>() => <TParams extends unknown[]>(rule: PermissionRule<TResource, TQuery, TParams>) => PermissionRule<TResource, TQuery, TParams>;
+
+/**
+ * A thin wrapper around
+ * {@link @backstage/plugin-permission-common#PermissionClient} that allows all
+ * backend-to-backend requests.
+ * @public
+ */
+declare class ServerPermissionClient implements PermissionAuthorizer {
+    private readonly permissionClient;
+    private readonly tokenManager;
+    private readonly permissionEnabled;
+    static fromConfig(config: Config, options: {
+        discovery: PluginEndpointDiscovery;
+        tokenManager: TokenManager;
+    }): ServerPermissionClient;
+    private constructor();
+    authorize(queries: AuthorizeQuery[], options?: AuthorizeRequestOptions): Promise<AuthorizeDecision[]>;
+    private isValidServerToken;
+}
+
+export { ApplyConditionsRequest, ApplyConditionsRequestEntry, ApplyConditionsResponse, ApplyConditionsResponseEntry, Condition, ConditionTransformer, ConditionalPolicyDecision, Conditions, DefinitivePolicyDecision, PermissionPolicy, PermissionRule, PolicyAuthorizeQuery, PolicyDecision, ServerPermissionClient, createConditionExports, createConditionFactory, createConditionTransformer, createPermissionIntegrationRouter, createPermissionRule, makeCreatePermissionRule };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/plugin-permission-node",
   "description": "Common permission and authorization utilities for backend plugins",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "license": "Apache-2.0",
@@ -33,11 +33,11 @@
     "start": "backstage-cli package start"
   },
   "dependencies": {
-    "@backstage/backend-common": "^0.10.8",
-    "@backstage/config": "^0.1.14",
-    "@backstage/errors": "^0.2.1",
-    "@backstage/plugin-auth-node": "^0.1.1",
-    "@backstage/plugin-permission-common": "^0.5.0",
+    "@backstage/backend-common": "^0.10.9",
+    "@backstage/config": "^0.1.15",
+    "@backstage/errors": "^0.2.2",
+    "@backstage/plugin-auth-node": "^0.1.2",
+    "@backstage/plugin-permission-common": "^0.5.1",
     "@types/express": "^4.17.6",
     "express": "^4.17.1",
     "express-promise-router": "^4.1.0",
@@ -52,5 +52,5 @@
   "files": [
     "dist"
   ],
-  "gitHead": "4805c3d13ce9bfc369e53c271b1b95e722b3b4dc"
+  "gitHead": "e244b348c473700e7d5e5fbcef38bd9f9fd1d0ba"
 }