From 370da15e7b225de270c8fc90f6cb8b817a02c859 Mon Sep 17 00:00:00 2001 From: Mike Lewis Date: Wed, 24 Nov 2021 14:30:21 +0000 Subject: [PATCH] permission-node: separate doc comment summaries with @remarks tag Signed-off-by: Mike Lewis --- plugins/permission-node/src/index.ts | 1 - .../src/integration/createConditionExports.ts | 6 +++++- .../src/integration/createConditionFactory.ts | 2 ++ .../src/integration/createPermissionIntegrationRouter.ts | 2 ++ plugins/permission-node/src/policy/types.ts | 9 +++++++++ plugins/permission-node/src/types.ts | 3 +++ 6 files changed, 21 insertions(+), 2 deletions(-) diff --git a/plugins/permission-node/src/index.ts b/plugins/permission-node/src/index.ts index 697c02ab22..39527bac71 100644 --- a/plugins/permission-node/src/index.ts +++ b/plugins/permission-node/src/index.ts @@ -19,7 +19,6 @@ * * @packageDocumentation */ - export * from './integration'; export * from './policy'; export * from './types'; diff --git a/plugins/permission-node/src/integration/createConditionExports.ts b/plugins/permission-node/src/integration/createConditionExports.ts index d69064a56c..30cff6628a 100644 --- a/plugins/permission-node/src/integration/createConditionExports.ts +++ b/plugins/permission-node/src/integration/createConditionExports.ts @@ -49,7 +49,11 @@ export type Conditions< /** * Creates the recommended condition-related exports for a given plugin based on the built-in - * {@link PermissionRule}s it supports. It returns a `conditions` object containing a + * {@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. diff --git a/plugins/permission-node/src/integration/createConditionFactory.ts b/plugins/permission-node/src/integration/createConditionFactory.ts index 8ee94091e1..84a8dc86a6 100644 --- a/plugins/permission-node/src/integration/createConditionFactory.ts +++ b/plugins/permission-node/src/integration/createConditionFactory.ts @@ -19,6 +19,8 @@ import { PermissionRule } from '../types'; /** * 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. diff --git a/plugins/permission-node/src/integration/createPermissionIntegrationRouter.ts b/plugins/permission-node/src/integration/createPermissionIntegrationRouter.ts index 7757678128..99e282b144 100644 --- a/plugins/permission-node/src/integration/createPermissionIntegrationRouter.ts +++ b/plugins/permission-node/src/integration/createPermissionIntegrationRouter.ts @@ -97,6 +97,8 @@ const applyConditions = ( * 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 diff --git a/plugins/permission-node/src/policy/types.ts b/plugins/permission-node/src/policy/types.ts index 36186d5e57..44380bad26 100644 --- a/plugins/permission-node/src/policy/types.ts +++ b/plugins/permission-node/src/policy/types.ts @@ -25,9 +25,12 @@ import { BackstageIdentity } from '@backstage/plugin-auth-backend'; /** * 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 */ export type PolicyAuthorizeRequest = Omit; @@ -35,6 +38,8 @@ export type PolicyAuthorizeRequest = Omit; /** * 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. @@ -54,6 +59,7 @@ export type ConditionalPolicyResult = { /** * The result of evaluating an authorization request with a {@link PermissionPolicy}. + * * @public */ export type PolicyResult = @@ -63,6 +69,8 @@ export type PolicyResult = /** * 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 @@ -71,6 +79,7 @@ export type PolicyResult = * 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 */ export interface PermissionPolicy { diff --git a/plugins/permission-node/src/types.ts b/plugins/permission-node/src/types.ts index a4e95fbd61..678befc99c 100644 --- a/plugins/permission-node/src/types.ts +++ b/plugins/permission-node/src/types.ts @@ -20,6 +20,8 @@ import type { PermissionCriteria } from '@backstage/plugin-permission-common'; * 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. @@ -27,6 +29,7 @@ import type { PermissionCriteria } from '@backstage/plugin-permission-common'; * 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 */ export type PermissionRule<