Support exportVariables policies

Signed-off-by: Andrew Haines <haines@cerbos.dev>

docs/core.derivedroles.derivedroles.md

@@ -12,5 +12,6 @@ A set of derived roles.
 derivedRoles: {
         name: string;
         definitions: DerivedRoleDefinition[];
+        variables?: Variables | undefined;
     };
 ```

docs/core.derivedroles.md

@@ -17,5 +17,5 @@ export interface DerivedRoles extends PolicyBase
 
 |  Property | Modifiers | Type | Description |
 |  --- | --- | --- | --- |
-|  [derivedRoles](./core.derivedroles.derivedroles.md) |  | { name: string; definitions: [DerivedRoleDefinition](./core.derivedroledefinition.md)<!-- -->\[\]; } | A set of derived roles. |
+|  [derivedRoles](./core.derivedroles.derivedroles.md) |  | { name: string; definitions: [DerivedRoleDefinition](./core.derivedroledefinition.md)<!-- -->\[\]; variables?: [Variables](./core.variables.md) \| undefined; } | A set of derived roles. |
 

docs/core.exportvariables.exportvariables.md

@@ -0,0 +1,16 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/core](./core.md) &gt; [ExportVariables](./core.exportvariables.md) &gt; [exportVariables](./core.exportvariables.exportvariables.md)
+
+## ExportVariables.exportVariables property
+
+A set of exported variables.
+
+**Signature:**
+
+```typescript
+exportVariables: {
+        name: string;
+        definitions: Record<string, string>;
+    };
+```

docs/core.exportvariables.md

@@ -0,0 +1,25 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/core](./core.md) &gt; [ExportVariables](./core.exportvariables.md)
+
+## ExportVariables interface
+
+A set of [exported variables](https://docs.cerbos.dev/cerbos/prerelease/policies/variables.html#export) to be reused in other policies.
+
+**Signature:**
+
+```typescript
+export interface ExportVariables extends PolicyBase 
+```
+**Extends:** [PolicyBase](./core.policybase.md)
+
+## Remarks
+
+Requires the Cerbos policy decision point server to be at least v0.29.
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [exportVariables](./core.exportvariables.exportvariables.md) |  | { name: string; definitions: Record&lt;string, string&gt;; } | A set of exported variables. |
+

docs/core.md

@@ -55,6 +55,7 @@ Common types used by the [gRPC](./grpc.md) and [HTTP](./http.md) client librarie
 |  [DisablePoliciesResponse](./core.disablepoliciesresponse.md) | The outcome of disabling policies. |
 |  [EnablePoliciesRequest](./core.enablepoliciesrequest.md) | Input to [Client.enablePolicies()](./core.client.enablepolicies.md)<!-- -->. |
 |  [EnablePoliciesResponse](./core.enablepoliciesresponse.md) | The outcome of enabling policies. |
+|  [ExportVariables](./core.exportvariables.md) | A set of [exported variables](https://docs.cerbos.dev/cerbos/prerelease/policies/variables.html#export) to be reused in other policies. |
 |  [GetPoliciesRequest](./core.getpoliciesrequest.md) | Input to [Client.getPolicies()](./core.client.getpolicies.md)<!-- -->. |
 |  [GetPoliciesResponse](./core.getpoliciesresponse.md) | Fetched policies. |
 |  [GetSchemasRequest](./core.getschemasrequest.md) | Input to [Client.getSchemas()](./core.client.getschemas.md)<!-- -->. |
@@ -93,6 +94,7 @@ Common types used by the [gRPC](./grpc.md) and [HTTP](./http.md) client librarie
 |  [SchemaRefs](./core.schemarefs.md) | References to schemas to be used to validate principal and resource attributes. |
 |  [ServerInfo](./core.serverinfo.md) | Information about the Cerbos policy decision point (PDP) server. |
 |  [ValidationError](./core.validationerror.md) | An error that occurred while validating the principal or resource attributes against a schema. |
+|  [Variables](./core.variables.md) | [Variables](https://docs.cerbos.dev/cerbos/prerelease/policies/variables.html) defined for use in policy conditions. |
 
 ## Variables
 
@@ -103,6 +105,7 @@ Common types used by the [gRPC](./grpc.md) and [HTTP](./http.md) client librarie
 |  [matchIsMatchExpr](./core.matchismatchexpr.md) | Type guard to check if a [Match](./core.match.md) is a [MatchExpr](./core.matchexpr.md)<!-- -->. |
 |  [matchIsMatchNone](./core.matchismatchnone.md) | Type guard to check if a [Match](./core.match.md) is a [MatchNone](./core.matchnone.md)<!-- -->. |
 |  [policyIsDerivedRoles](./core.policyisderivedroles.md) | Type guard to check if a [Policy](./core.policy.md) is a set of [DerivedRoles](./core.derivedroles.md)<!-- -->. |
+|  [policyIsExportVariables](./core.policyisexportvariables.md) | Type guard to check if a [Policy](./core.policy.md) is a set of [ExportVariables](./core.exportvariables.md)<!-- -->. |
 |  [policyIsPrincipalPolicy](./core.policyisprincipalpolicy.md) | Type guard to check if a [Policy](./core.policy.md) is a [PrincipalPolicy](./core.principalpolicy.md)<!-- -->. |
 |  [policyIsResourcePolicy](./core.policyisresourcepolicy.md) | Type guard to check if a [Policy](./core.policy.md) is a [ResourcePolicy](./core.resourcepolicy.md)<!-- -->. |
 

docs/core.policy.md

@@ -9,7 +9,7 @@ A [policy](https://docs.cerbos.dev/cerbos/latest/policies/index.html) definition
 **Signature:**
 
 ```typescript
-export type Policy = DerivedRoles | PrincipalPolicy | ResourcePolicy;
+export type Policy = DerivedRoles | ExportVariables | PrincipalPolicy | ResourcePolicy;
 ```
-**References:** [DerivedRoles](./core.derivedroles.md)<!-- -->, [PrincipalPolicy](./core.principalpolicy.md)<!-- -->, [ResourcePolicy](./core.resourcepolicy.md)
+**References:** [DerivedRoles](./core.derivedroles.md)<!-- -->, [ExportVariables](./core.exportvariables.md)<!-- -->, [PrincipalPolicy](./core.principalpolicy.md)<!-- -->, [ResourcePolicy](./core.resourcepolicy.md)
 

docs/core.policybase.variables.md

@@ -4,6 +4,11 @@
 
 ## PolicyBase.variables property
 
+> Warning: This API is now obsolete.
+> 
+> Define variables within the policy body instead (provided the Cerbos policy decision point server is at least v0.29).
+> 
+
 Variable expressions defined for the policy.
 
 **Signature:**

docs/core.policyisexportvariables.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; [policyIsExportVariables](./core.policyisexportvariables.md)
+
+## policyIsExportVariables variable
+
+Type guard to check if a [Policy](./core.policy.md) is a set of [ExportVariables](./core.exportvariables.md)<!-- -->.
+
+**Signature:**
+
+```typescript
+policyIsExportVariables: (policy: Policy) => policy is ExportVariables
+```

docs/core.principalpolicy.md

@@ -17,5 +17,5 @@ export interface PrincipalPolicy extends PolicyBase
 
 |  Property | Modifiers | Type | Description |
 |  --- | --- | --- | --- |
-|  [principalPolicy](./core.principalpolicy.principalpolicy.md) |  | { principal: string; version: string; rules: [PrincipalRule](./core.principalrule.md)<!-- -->\[\]; scope?: string; } | The policy body. |
+|  [principalPolicy](./core.principalpolicy.principalpolicy.md) |  | { principal: string; version: string; rules: [PrincipalRule](./core.principalrule.md)<!-- -->\[\]; scope?: string; variables?: [Variables](./core.variables.md) \| undefined; } | The policy body. |
 

docs/core.principalpolicy.principalpolicy.md

@@ -14,5 +14,6 @@ principalPolicy: {
         version: string;
         rules: PrincipalRule[];
         scope?: string;
+        variables?: Variables | undefined;
     };
 ```

docs/core.resourcepolicy.md

@@ -17,5 +17,5 @@ export interface ResourcePolicy extends PolicyBase
 
 |  Property | Modifiers | Type | Description |
 |  --- | --- | --- | --- |
-|  [resourcePolicy](./core.resourcepolicy.resourcepolicy.md) |  | { resource: string; version: string; importDerivedRoles?: string\[\]; rules: [ResourceRule](./core.resourcerule.md)<!-- -->\[\]; scope?: string; schemas?: [SchemaRefs](./core.schemarefs.md) \| undefined; } | The policy body. |
+|  [resourcePolicy](./core.resourcepolicy.resourcepolicy.md) |  | { resource: string; version: string; importDerivedRoles?: string\[\]; rules: [ResourceRule](./core.resourcerule.md)<!-- -->\[\]; scope?: string; schemas?: [SchemaRefs](./core.schemarefs.md) \| undefined; variables?: [Variables](./core.variables.md) \| undefined; } | The policy body. |
 

docs/core.resourcepolicy.resourcepolicy.md

@@ -16,5 +16,6 @@ resourcePolicy: {
         rules: ResourceRule[];
         scope?: string;
         schemas?: SchemaRefs | undefined;
+        variables?: Variables | undefined;
     };
 ```

docs/core.variables.import.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; [Variables](./core.variables.md) &gt; [import](./core.variables.import.md)
+
+## Variables.import property
+
+Names of variable sets to import.
+
+**Signature:**
+
+```typescript
+import?: string[];
+```

docs/core.variables.local.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; [Variables](./core.variables.md) &gt; [local](./core.variables.local.md)
+
+## Variables.local property
+
+Variable expressions defined for the policy.
+
+**Signature:**
+
+```typescript
+local?: Record<string, string>;
+```

docs/core.variables.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; [Variables](./core.variables.md)
+
+## Variables interface
+
+[Variables](https://docs.cerbos.dev/cerbos/prerelease/policies/variables.html) defined for use in policy conditions.
+
+**Signature:**
+
+```typescript
+export interface Variables 
+```
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [import?](./core.variables.import.md) |  | string\[\] | _(Optional)_ Names of variable sets to import. |
+|  [local?](./core.variables.local.md) |  | Record&lt;string, string&gt; | _(Optional)_ Variable expressions defined for the policy. |
+

package.json

@@ -14,7 +14,7 @@
     "build": "tsc --build",
     "build:watch": "tsc --build --watch",
     "clean": "rm -rf api packages/*/lib",
-    "docs": "npm run docs:extract-api && npm run docs:generate && npm run docs:fixup",
+    "docs": "npm run build && npm run docs:extract-api && npm run docs:generate && npm run docs:fixup",
     "docs:extract-api": "npm --workspace=packages/core --workspace=packages/grpc --workspace=packages/http --workspace=packages/lite --workspace=packages/opentelemetry exec api-extractor run",
     "docs:fixup": "scripts/sed-all docs 's/\\r$//'",
     "docs:generate": "api-documenter markdown --input-folder api --output-folder docs",

packages/core/CHANGELOG.md

@@ -6,6 +6,10 @@
 
   Requires a policy decision point server running Cerbos 0.29+.
 
+- Support for [exporting and importing variable sets](https://docs.cerbos.dev/cerbos/prerelease/policies/variables.html) in policies ([#598](https://github.com/cerbos/cerbos-sdk-javascript/pull/598))
+
+  Requires a policy decision point server running Cerbos 0.29+.
+
 ## [0.11.0] - 2023-06-07
 
 ### Added

packages/core/src/convert/fromProtobuf.ts

@@ -7,6 +7,7 @@ import { PlanResourcesFilter_Kind } from "../protobuf/cerbos/engine/v1/engine";
 import type {
   Condition as ConditionProtobuf,
   DerivedRoles as DerivedRolesProtobuf,
+  ExportVariables as ExportVariablesProtobuf,
   Match as MatchProtobuf,
   Match_ExprList,
   Metadata,
@@ -20,6 +21,7 @@ import type {
   RoleDef,
   Schemas,
   Schemas_Schema,
+  Variables as VariablesProtobuf,
 } from "../protobuf/cerbos/policy/v1/policy";
 import type {
   CheckResourcesResponse as CheckResourcesResponseProtobuf,
@@ -45,6 +47,7 @@ import type {
   DerivedRoles,
   DisablePoliciesResponse,
   EnablePoliciesResponse,
+  ExportVariables,
   GetPoliciesResponse,
   ListPoliciesResponse,
   ListSchemasResponse,
@@ -68,6 +71,7 @@ import type {
   SchemaRefs,
   ValidationError,
   Value,
+  Variables,
 } from "../types/external";
 import {
   CheckResourcesResponse,
@@ -227,6 +231,9 @@ const policyTypeFromProtobuf = (
     case "derivedRoles":
       return derivedRolesFromProtobuf(policyType.derivedRoles);
 
+    case "exportVariables":
+      return exportVariablesFromProtobuf(policyType.exportVariables);
+
     case "principalPolicy":
       return principalPolicyFromProtobuf(policyType.principalPolicy);
 
@@ -243,10 +250,12 @@ const policyTypeFromProtobuf = (
 const derivedRolesFromProtobuf = ({
   name,
   definitions,
+  variables,
 }: DerivedRolesProtobuf): OmitPolicyBase<DerivedRoles> => ({
   derivedRoles: {
     name,
     definitions: definitions.map(derivedRoleDefinitionFromProtobuf),
+    variables: variables && variablesFromProtobuf(variables),
   },
 });
 
@@ -305,17 +314,37 @@ const matchesFromProtobuf = ({ of }: Match_ExprList): Matches => ({
   of: of.map(matchFromProtobuf),
 });
 
+const variablesFromProtobuf = ({
+  import: imports,
+  local,
+}: VariablesProtobuf): Variables => ({
+  import: imports,
+  local,
+});
+
+const exportVariablesFromProtobuf = ({
+  name,
+  definitions,
+}: ExportVariablesProtobuf): OmitPolicyBase<ExportVariables> => ({
+  exportVariables: {
+    name,
+    definitions,
+  },
+});
+
 const principalPolicyFromProtobuf = ({
   principal,
   version,
   rules,
   scope,
+  variables,
 }: PrincipalPolicyProtobuf): OmitPolicyBase<PrincipalPolicy> => ({
   principalPolicy: {
     principal,
     version,
     rules: rules.map(principalRuleFromProtobuf),
     scope,
+    variables: variables && variablesFromProtobuf(variables),
   },
 });
 
@@ -350,6 +379,7 @@ const resourcePolicyFromProtobuf = ({
   rules,
   schemas,
   scope,
+  variables,
 }: ResourcePolicyProtobuf): OmitPolicyBase<ResourcePolicy> => ({
   resourcePolicy: {
     resource,
@@ -358,6 +388,7 @@ const resourcePolicyFromProtobuf = ({
     rules: rules.map(resourceRuleFromProtobuf),
     schemas: schemas && schemaRefsFromProtobuf(schemas),
     scope,
+    variables: variables && variablesFromProtobuf(variables),
   },
 });