Add support for user-defined policy rule outputs

cerbos/cerbos#1594 Signed-off-by: Andrew Haines <haines@cerbos.dev>
haines · Jun 1, 2023 · 91f64e7 · 91f64e7
1 parent f761ae9
commit 91f64e7
Show file tree

Hide file tree

Showing 54 changed files with 718 additions and 18 deletions.
diff --git a/docs/core.checkresourcesresult._constructor_.md b/docs/core.checkresourcesresult._constructor_.md
@@ -9,12 +9,12 @@ Constructs a new instance of the `CheckResourcesResult` class
 **Signature:**
 
 ```typescript
-constructor({ resource, actions, validationErrors, metadata, }: Pick<CheckResourcesResult, "resource" | "actions" | "validationErrors" | "metadata">);
+constructor({ resource, actions, validationErrors, metadata, outputs, }: Pick<CheckResourcesResult, "resource" | "actions" | "validationErrors" | "metadata" | "outputs">);
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  { resource, actions, validationErrors, metadata, } | Pick&lt;[CheckResourcesResult](./core.checkresourcesresult.md)<!-- -->, "resource" \| "actions" \| "validationErrors" \| "metadata"&gt; |  |
+|  { resource, actions, validationErrors, metadata, outputs, } | Pick&lt;[CheckResourcesResult](./core.checkresourcesresult.md)<!-- -->, "resource" \| "actions" \| "validationErrors" \| "metadata" \| "outputs"&gt; |  |
 
diff --git a/docs/core.checkresourcesresult.md b/docs/core.checkresourcesresult.md
@@ -16,14 +16,15 @@ export declare class CheckResourcesResult
 
 |  Constructor | Modifiers | Description |
 |  --- | --- | --- |
-|  [(constructor)({ resource, actions, validationErrors, metadata, })](./core.checkresourcesresult._constructor_.md) |  | Constructs a new instance of the <code>CheckResourcesResult</code> class |
+|  [(constructor)({ resource, actions, validationErrors, metadata, outputs, })](./core.checkresourcesresult._constructor_.md) |  | Constructs a new instance of the <code>CheckResourcesResult</code> class |
 
 ## Properties
 
 |  Property | Modifiers | Type | Description |
 |  --- | --- | --- | --- |
 |  [actions](./core.checkresourcesresult.actions.md) |  | Record&lt;string, [Effect](./core.effect.md) \| undefined&gt; | The policy decisions for each action. |
 |  [metadata](./core.checkresourcesresult.metadata.md) |  | [CheckResourcesResultMetadata](./core.checkresourcesresultmetadata.md) \| undefined | Additional information about how the policy decisions were reached. |
+|  [outputs](./core.checkresourcesresult.outputs.md) |  | [OutputResult](./core.outputresult.md)<!-- -->\[\] | User-defined outputs from policy rule evaluations. |
 |  [resource](./core.checkresourcesresult.resource.md) |  | [CheckResourcesResultResource](./core.checkresourcesresultresource.md) | The resource that was checked. |
 |  [validationErrors](./core.checkresourcesresult.validationerrors.md) |  | [ValidationError](./core.validationerror.md)<!-- -->\[\] | Any schema validation errors for the principal or resource attributes. |
 
@@ -34,4 +35,5 @@ export declare class CheckResourcesResult
 |  [allAllowed()](./core.checkresourcesresult.allallowed.md) |  | Check if the policy decision was that all input actions should be allowed for the resource. |
 |  [allowedActions()](./core.checkresourcesresult.allowedactions.md) |  | List the actions that should be allowed for the resource. |
 |  [isAllowed(action)](./core.checkresourcesresult.isallowed.md) |  | Check if the policy decision was that a given action should be allowed for the resource. |
+|  [output(source)](./core.checkresourcesresult.output.md) |  | Find the value of the user-defined output for a particular policy rule. |
 
diff --git a/docs/core.checkresourcesresult.output.md b/docs/core.checkresourcesresult.output.md
@@ -0,0 +1,26 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/core](./core.md) &gt; [CheckResourcesResult](./core.checkresourcesresult.md) &gt; [output](./core.checkresourcesresult.output.md)
+
+## CheckResourcesResult.output() method
+
+Find the value of the user-defined output for a particular policy rule.
+
+**Signature:**
+
+```typescript
+output(source: string): Value | undefined;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  source | string | the identifier of the policy rule that produced the output. |
+
+**Returns:**
+
+[Value](./core.value.md) \| undefined
+
+`undefined` if the result does not include an output for the source.
+
diff --git a/docs/core.checkresourcesresult.outputs.md b/docs/core.checkresourcesresult.outputs.md
@@ -0,0 +1,18 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/core](./core.md) &gt; [CheckResourcesResult](./core.checkresourcesresult.md) &gt; [outputs](./core.checkresourcesresult.outputs.md)
+
+## CheckResourcesResult.outputs property
+
+User-defined outputs from policy rule evaluations.
+
+**Signature:**
+
+```typescript
+outputs: OutputResult[];
+```
+
+## Remarks
+
+Requires the Cerbos policy decision point server to be at least v0.27.
+
diff --git a/docs/core.md b/docs/core.md
@@ -69,6 +69,8 @@ Common types used by the [gRPC](./grpc.md) and [HTTP](./http.md) client librarie
 |  [MatchExpr](./core.matchexpr.md) | A single expression to evaluate in a condition. |
 |  [MatchNone](./core.matchnone.md) | A set of expressions to evaluate in a condition that must all be false. |
 |  [Options](./core.options.md) | Options for creating a new [Client](./core.client.md)<!-- -->. |
+|  [Output](./core.output.md) | User-defined output to be produced when evaluating a policy rule. |
+|  [OutputResult](./core.outputresult.md) | User-defined output from a policy rule evaluation. |
 |  [PlanResourcesConditionalResponse](./core.planresourcesconditionalresponse.md) | A query plan for when the specified action is conditionally allowed for the principal on resources matching the input. |
 |  [PlanResourcesMetadata](./core.planresourcesmetadata.md) | Additional information about the query plan. |
 |  [PlanResourcesRequest](./core.planresourcesrequest.md) | Input to [Client.planResources()](./core.client.planresources.md)<!-- -->. |

diff --git a/docs/core.output.expr.md b/docs/core.output.expr.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/core](./core.md) &gt; [Output](./core.output.md) &gt; [expr](./core.output.expr.md)
+
+## Output.expr property
+
+A [Common Expression Language](https://docs.cerbos.dev/cerbos/latest/policies/conditions.html) expression to evaluate.
+
+**Signature:**
+
+```typescript
+expr: string;
+```
diff --git a/docs/core.output.md b/docs/core.output.md
@@ -0,0 +1,20 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/core](./core.md) &gt; [Output](./core.output.md)
+
+## Output interface
+
+User-defined output to be produced when evaluating a policy rule.
+
+**Signature:**
+
+```typescript
+export interface Output 
+```
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [expr](./core.output.expr.md) |  | string | A [Common Expression Language](https://docs.cerbos.dev/cerbos/latest/policies/conditions.html) expression to evaluate. |
+
diff --git a/docs/core.outputresult.md b/docs/core.outputresult.md
@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/core](./core.md) &gt; [OutputResult](./core.outputresult.md)
+
+## OutputResult interface
+
+User-defined output from a policy rule evaluation.
+
+**Signature:**
+
+```typescript
+export interface OutputResult 
+```
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [source](./core.outputresult.source.md) |  | string | The identifier of the policy rule that produced the output. |
+|  [value](./core.outputresult.value.md) |  | [Value](./core.value.md) \| undefined | The result of evaluating the output expression. |
+
diff --git a/docs/core.outputresult.source.md b/docs/core.outputresult.source.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/core](./core.md) &gt; [OutputResult](./core.outputresult.md) &gt; [source](./core.outputresult.source.md)
+
+## OutputResult.source property
+
+The identifier of the policy rule that produced the output.
+
+**Signature:**
+
+```typescript
+source: string;
+```
diff --git a/docs/core.outputresult.value.md b/docs/core.outputresult.value.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/core](./core.md) &gt; [OutputResult](./core.outputresult.md) &gt; [value](./core.outputresult.value.md)
+
+## OutputResult.value property
+
+The result of evaluating the output expression.
+
+**Signature:**
+
+```typescript
+value: Value | undefined;
+```
diff --git a/docs/core.principalruleaction.md b/docs/core.principalruleaction.md
@@ -20,4 +20,5 @@ export interface PrincipalRuleAction
 |  [condition?](./core.principalruleaction.condition.md) |  | [Condition](./core.condition.md) \| undefined | _(Optional)_ The condition that must be met for the override to apply. |
 |  [effect](./core.principalruleaction.effect.md) |  | [Effect](./core.effect.md) | The effect of the override. |
 |  [name?](./core.principalruleaction.name.md) |  | string | _(Optional)_ A descriptive name for the rule. |
+|  [output?](./core.principalruleaction.output.md) |  | [Output](./core.output.md) \| undefined | _(Optional)_ User-defined output to be produced when evaluating the rule. |
 
diff --git a/docs/core.principalruleaction.output.md b/docs/core.principalruleaction.output.md
@@ -0,0 +1,18 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/core](./core.md) &gt; [PrincipalRuleAction](./core.principalruleaction.md) &gt; [output](./core.principalruleaction.output.md)
+
+## PrincipalRuleAction.output property
+
+User-defined output to be produced when evaluating the rule.
+
+**Signature:**
+
+```typescript
+output?: Output | undefined;
+```
+
+## Remarks
+
+Requires the Cerbos policy decision point server to be at least v0.27.
+
diff --git a/docs/core.resourcerule.md b/docs/core.resourcerule.md
@@ -21,5 +21,6 @@ export interface ResourceRule
 |  [derivedRoles?](./core.resourcerule.derivedroles.md) |  | string\[\] | _(Optional)_ Derived roles to which the rule applies. |
 |  [effect](./core.resourcerule.effect.md) |  | [Effect](./core.effect.md) | The effect of the rule. |
 |  [name?](./core.resourcerule.name.md) |  | string | _(Optional)_ A descriptive name for the rule. |
+|  [output?](./core.resourcerule.output.md) |  | [Output](./core.output.md) \| undefined | _(Optional)_ User-defined output to be produced when evaluating the rule. |
 |  [roles?](./core.resourcerule.roles.md) |  | string\[\] | _(Optional)_ Static roles to which the rule applies. |
 
diff --git a/docs/core.resourcerule.output.md b/docs/core.resourcerule.output.md
@@ -0,0 +1,18 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/core](./core.md) &gt; [ResourceRule](./core.resourcerule.md) &gt; [output](./core.resourcerule.output.md)
+
+## ResourceRule.output property
+
+User-defined output to be produced when evaluating the rule.
+
+**Signature:**
+
+```typescript
+output?: Output | undefined;
+```
+
+## Remarks
+
+Requires the Cerbos policy decision point server to be at least v0.27.
+
diff --git a/packages/core/CHANGELOG.md b/packages/core/CHANGELOG.md
@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+### Added
+
+- Support for user-defined policy rule outputs ([#542](https://github.com/cerbos/cerbos-sdk-javascript/pull/542))
+
+  Requires a policy decision point server running Cerbos 0.27+.
+
 ### Removed
 
 - Support for Node.js 14, which is now [end-of-life](https://github.com/nodejs/release#end-of-life-releases) ([#521](https://github.com/cerbos/cerbos-sdk-javascript/pull/521))

diff --git a/packages/core/src/convert/fromProtobuf.ts b/packages/core/src/convert/fromProtobuf.ts
@@ -1,5 +1,8 @@
 import { Effect as EffectProtobuf } from "../protobuf/cerbos/effect/v1/effect";
-import type { PlanResourcesFilter_Expression_Operand } from "../protobuf/cerbos/engine/v1/engine";
+import type {
+  OutputEntry as OutputEntry,
+  PlanResourcesFilter_Expression_Operand,
+} from "../protobuf/cerbos/engine/v1/engine";
 import { PlanResourcesFilter_Kind } from "../protobuf/cerbos/engine/v1/engine";
 import type {
   Condition as ConditionProtobuf,
@@ -46,6 +49,7 @@ import type {
   ListSchemasResponse,
   Match,
   Matches,
+  OutputResult,
   PlanExpressionOperand,
   PlanResourcesMetadata,
   PlanResourcesResponse,
@@ -92,6 +96,7 @@ const checkResourcesResultFromProtobuf = ({
   actions,
   validationErrors,
   meta,
+  outputs,
 }: CheckResourcesResponse_ResultEntry): CheckResourcesResult => {
   if (!resource) {
     throw new Error("Missing resource on CheckResources result");
@@ -102,6 +107,7 @@ const checkResourcesResultFromProtobuf = ({
     actions: actionsFromProtobuf(actions),
     validationErrors: validationErrors.map(validationErrorFromProtobuf),
     metadata: meta,
+    outputs: outputs.map(outputResultFromProtobuf),
   });
 };
 
@@ -147,6 +153,14 @@ const validationErrorSourceFromProtobuf = (
   }
 };
 
+const outputResultFromProtobuf = ({
+  src,
+  val,
+}: OutputEntry): OutputResult => ({
+  source: src,
+  value: val as Value | undefined,
+});
+
 export const deleteSchemasResponseFromProtobuf = ({
   deletedSchemas,
 }: DeleteSchemaResponse): DeleteSchemasResponse => ({

diff --git a/packages/core/src/convert/toProtobuf.ts b/packages/core/src/convert/toProtobuf.ts
@@ -11,6 +11,7 @@ import type {
   DerivedRoles as DerivedRolesProtobuf,
   Match as MatchProtobuf,
   Match_ExprList,
+  Output as OutputProtobuf,
   Policy as PolicyProtobuf,
   PrincipalPolicy as PrincipalPolicyProtobuf,
   PrincipalRule as PrincipalRuleProtobuf,
@@ -52,6 +53,7 @@ import type {
   ListPoliciesRequest,
   Match,
   Matches,
+  Output,
   PlanResourcesRequest,
   Policy,
   Principal,
@@ -225,18 +227,22 @@ const principalRuleActionToProtobuf = ({
   effect,
   condition,
   name = "",
+  output,
 }: PrincipalRuleAction): PrincipalRule_Action => ({
   action,
   effect: effectToProtobuf(effect),
   condition: condition && conditionToProtobuf(condition),
   name,
+  output: output && outputToProtobuf(output),
 });
 
 const effectToProtobuf = (effect: Effect): EffectProtobuf =>
   effect === Effect.ALLOW
     ? EffectProtobuf.EFFECT_ALLOW
     : EffectProtobuf.EFFECT_DENY;
 
+const outputToProtobuf = ({ expr }: Output): OutputProtobuf => ({ expr });
+
 const resourcePolicyToProtobuf = ({
   resourcePolicy: {
     resource,
@@ -262,13 +268,15 @@ const resourceRuleToProtobuf = ({
   roles = [],
   condition,
   name = "",
+  output,
 }: ResourceRule): ResourceRuleProtobuf => ({
   actions,
   effect: effectToProtobuf(effect),
   derivedRoles,
   roles,
   condition: condition && conditionToProtobuf(condition),
   name,
+  output: output && outputToProtobuf(output),
 });
 
 const policySchemasToProtobuf = ({

diff --git a/packages/core/src/protobuf/cerbos/engine/v1/engine.ts b/packages/core/src/protobuf/cerbos/engine/v1/engine.ts
diff --git a/packages/core/src/protobuf/cerbos/policy/v1/policy.ts b/packages/core/src/protobuf/cerbos/policy/v1/policy.ts