feat: Support exportVariables policies (#598)

* Normalize `toJSON` output by omitting fields set to their default values
  stephenh/ts-proto#878
* Regenerate protobuf code
* Support `exportVariables` policies
* Extract policy body types for better documentation
* Enforce consistent ordering of type vs regular imports

Signed-off-by: Andrew Haines <[email protected]>

.eslintrc.yaml

@@ -40,6 +40,7 @@ rules:
     - error
     - alphabetize:
         order: asc
+        orderImportKind: asc
         caseInsensitive: true
       newlines-between: always
   no-console: error

docs/core.derivedroles.derivedroles.md

@@ -9,8 +9,5 @@ A set of derived roles.
 **Signature:**
 
 ```typescript
-derivedRoles: {
-        name: string;
-        definitions: DerivedRoleDefinition[];
-    };
+derivedRoles: DerivedRolesBody;
 ```

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) |  | [DerivedRolesBody](./core.derivedrolesbody.md) | A set of derived roles. |
 

docs/core.derivedrolesbody.definitions.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; [DerivedRolesBody](./core.derivedrolesbody.md) &gt; [definitions](./core.derivedrolesbody.definitions.md)
+
+## DerivedRolesBody.definitions property
+
+The definitions of the derived roles.
+
+**Signature:**
+
+```typescript
+definitions: DerivedRoleDefinition[];
+```

docs/core.derivedrolesbody.md

@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/core](./core.md) &gt; [DerivedRolesBody](./core.derivedrolesbody.md)
+
+## DerivedRolesBody interface
+
+A set of [derived roles](https://docs.cerbos.dev/cerbos/latest/policies/derived_roles.html) to augment static RBAC roles with contextual data to provide more fine-grained control at runtime.
+
+**Signature:**
+
+```typescript
+export interface DerivedRolesBody 
+```
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [definitions](./core.derivedrolesbody.definitions.md) |  | [DerivedRoleDefinition](./core.derivedroledefinition.md)<!-- -->\[\] | The definitions of the derived roles. |
+|  [name](./core.derivedrolesbody.name.md) |  | string | The name to use when importing the set of derived roles. |
+|  [variables?](./core.derivedrolesbody.variables.md) |  | [Variables](./core.variables.md) \| undefined | _(Optional)_ [Variables](https://docs.cerbos.dev/cerbos/prerelease/policies/variables.html) defined for use in conditions. |
+

docs/core.derivedrolesbody.name.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; [DerivedRolesBody](./core.derivedrolesbody.md) &gt; [name](./core.derivedrolesbody.name.md)
+
+## DerivedRolesBody.name property
+
+The name to use when importing the set of derived roles.
+
+**Signature:**
+
+```typescript
+name: string;
+```

docs/core.derivedrolesbody.variables.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; [DerivedRolesBody](./core.derivedrolesbody.md) &gt; [variables](./core.derivedrolesbody.variables.md)
+
+## DerivedRolesBody.variables property
+
+[Variables](https://docs.cerbos.dev/cerbos/prerelease/policies/variables.html) defined for use in conditions.
+
+**Signature:**
+
+```typescript
+variables?: Variables | undefined;
+```
+
+## Remarks
+
+Requires the Cerbos policy decision point server to be at least v0.29.
+

docs/core.exportvariables.exportvariables.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; [ExportVariables](./core.exportvariables.md) &gt; [exportVariables](./core.exportvariables.exportvariables.md)
+
+## ExportVariables.exportVariables property
+
+A set of exported variables.
+
+**Signature:**
+
+```typescript
+exportVariables: ExportVariablesBody;
+```

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) |  | [ExportVariablesBody](./core.exportvariablesbody.md) | A set of exported variables. |
+

docs/core.exportvariablesbody.definitions.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; [ExportVariablesBody](./core.exportvariablesbody.md) &gt; [definitions](./core.exportvariablesbody.definitions.md)
+
+## ExportVariablesBody.definitions property
+
+Variable expressions.
+
+**Signature:**
+
+```typescript
+definitions: Record<string, string>;
+```

docs/core.exportvariablesbody.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; [ExportVariablesBody](./core.exportvariablesbody.md)
+
+## ExportVariablesBody 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 ExportVariablesBody 
+```
+
+## Remarks
+
+Requires the Cerbos policy decision point server to be at least v0.29.
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [definitions](./core.exportvariablesbody.definitions.md) |  | Record&lt;string, string&gt; | Variable expressions. |
+|  [name](./core.exportvariablesbody.name.md) |  | string | The name to use when importing the set of variables. |
+

docs/core.exportvariablesbody.name.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; [ExportVariablesBody](./core.exportvariablesbody.md) &gt; [name](./core.exportvariablesbody.name.md)
+
+## ExportVariablesBody.name property
+
+The name to use when importing the set of variables.
+
+**Signature:**
+
+```typescript
+name: string;
+```

docs/core.md

@@ -51,10 +51,13 @@ Common types used by the [gRPC](./grpc.md) and [HTTP](./http.md) client librarie
 |  [DeleteSchemasResponse](./core.deleteschemasresponse.md) | The outcome of deleting schemas. |
 |  [DerivedRoleDefinition](./core.derivedroledefinition.md) | The definition of a [derived role](https://docs.cerbos.dev/cerbos/latest/policies/derived_roles.html)<!-- -->. |
 |  [DerivedRoles](./core.derivedroles.md) | A set of [derived roles](https://docs.cerbos.dev/cerbos/latest/policies/derived_roles.html) to augment static RBAC roles with contextual data to provide more fine-grained control at runtime. |
+|  [DerivedRolesBody](./core.derivedrolesbody.md) | A set of [derived roles](https://docs.cerbos.dev/cerbos/latest/policies/derived_roles.html) to augment static RBAC roles with contextual data to provide more fine-grained control at runtime. |
 |  [DisablePoliciesRequest](./core.disablepoliciesrequest.md) | Input to [Client.disablePolicies()](./core.client.disablepolicies.md)<!-- -->. |
 |  [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. |
+|  [ExportVariablesBody](./core.exportvariablesbody.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)<!-- -->. |
@@ -80,19 +83,22 @@ Common types used by the [gRPC](./grpc.md) and [HTTP](./http.md) client librarie
 |  [PolicyMetadata](./core.policymetadata.md) | Metadata describing a policy. |
 |  [Principal](./core.principal.md) | A principal (often a user, but potentially another actor like a service account) to authorize. |
 |  [PrincipalPolicy](./core.principalpolicy.md) | A [policy](https://docs.cerbos.dev/cerbos/latest/policies/principal_policies.html) defining overrides for a specific user. |
+|  [PrincipalPolicyBody](./core.principalpolicybody.md) | A [policy](https://docs.cerbos.dev/cerbos/latest/policies/principal_policies.html) defining overrides for a specific user. |
 |  [PrincipalRule](./core.principalrule.md) | A rule defining an override for a specific user. |
 |  [PrincipalRuleAction](./core.principalruleaction.md) | An override for a given action for a specific user. |
 |  [ReloadStoreRequest](./core.reloadstorerequest.md) | Input to [Client.reloadStore()](./core.client.reloadstore.md)<!-- -->. |
 |  [Resource](./core.resource.md) | A resource on which to check a principal's permissions. |
 |  [ResourceCheck](./core.resourcecheck.md) | A [Resource](./core.resource.md) and list of actions on which to check a principal's permissions. |
 |  [ResourcePolicy](./core.resourcepolicy.md) | A [policy](https://docs.cerbos.dev/cerbos/latest/policies/resource_policies.html) defining rules for actions that can be performed on a given resource. |
+|  [ResourcePolicyBody](./core.resourcepolicybody.md) | A [policy](https://docs.cerbos.dev/cerbos/latest/policies/resource_policies.html) defining rules for actions that can be performed on a given resource. |
 |  [ResourceRule](./core.resourcerule.md) | A rule for actions that can be performed on a given resource. |
 |  [Schema](./core.schema.md) | A JSON schema used to validate principal or resource attributes. |
 |  [SchemaInput](./core.schemainput.md) | A JSON schema to be used to validate principal or resource attributes. |
 |  [SchemaRef](./core.schemaref.md) | Reference to a schema to be used to validate principal or resource attributes. |
 |  [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 +109,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 ([DerivedRolesBody.variables](./core.derivedrolesbody.variables.md)<!-- -->, [PrincipalPolicyBody.variables](./core.principalpolicybody.variables.md)<!-- -->, or [ResourcePolicyBody.variables](./core.resourcepolicybody.variables.md)<!-- -->).
+> 
+
 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) |  | [PrincipalPolicyBody](./core.principalpolicybody.md) | The policy body. |
 

docs/core.principalpolicy.principalpolicy.md

@@ -9,10 +9,5 @@ The policy body.
 **Signature:**
 
 ```typescript
-principalPolicy: {
-        principal: string;
-        version: string;
-        rules: PrincipalRule[];
-        scope?: string;
-    };
+principalPolicy: PrincipalPolicyBody;
 ```

docs/core.principalpolicybody.md

@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/core](./core.md) &gt; [PrincipalPolicyBody](./core.principalpolicybody.md)
+
+## PrincipalPolicyBody interface
+
+A [policy](https://docs.cerbos.dev/cerbos/latest/policies/principal_policies.html) defining overrides for a specific user.
+
+**Signature:**
+
+```typescript
+export interface PrincipalPolicyBody 
+```
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [principal](./core.principalpolicybody.principal.md) |  | string | The ID of the principal to whom the policy applies. |
+|  [rules](./core.principalpolicybody.rules.md) |  | [PrincipalRule](./core.principalrule.md)<!-- -->\[\] | Rules defining the overrides that apply to the principal. |
+|  [scope?](./core.principalpolicybody.scope.md) |  | string | _(Optional)_ [Scope](https://docs.cerbos.dev/cerbos/latest/policies/scoped_policies.html) of the policy. |
+|  [variables?](./core.principalpolicybody.variables.md) |  | [Variables](./core.variables.md) \| undefined | _(Optional)_ [Variables](https://docs.cerbos.dev/cerbos/prerelease/policies/variables.html) defined for use in conditions. |
+|  [version](./core.principalpolicybody.version.md) |  | string | The version of the policy. |
+

docs/core.principalpolicybody.principal.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; [PrincipalPolicyBody](./core.principalpolicybody.md) &gt; [principal](./core.principalpolicybody.principal.md)
+
+## PrincipalPolicyBody.principal property
+
+The ID of the principal to whom the policy applies.
+
+**Signature:**
+
+```typescript
+principal: string;
+```

docs/core.principalpolicybody.rules.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; [PrincipalPolicyBody](./core.principalpolicybody.md) &gt; [rules](./core.principalpolicybody.rules.md)
+
+## PrincipalPolicyBody.rules property
+
+Rules defining the overrides that apply to the principal.
+
+**Signature:**
+
+```typescript
+rules: PrincipalRule[];
+```

docs/core.principalpolicybody.scope.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; [PrincipalPolicyBody](./core.principalpolicybody.md) &gt; [scope](./core.principalpolicybody.scope.md)
+
+## PrincipalPolicyBody.scope property
+
+[Scope](https://docs.cerbos.dev/cerbos/latest/policies/scoped_policies.html) of the policy.
+
+**Signature:**
+
+```typescript
+scope?: string;
+```

docs/core.principalpolicybody.variables.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; [PrincipalPolicyBody](./core.principalpolicybody.md) &gt; [variables](./core.principalpolicybody.variables.md)
+
+## PrincipalPolicyBody.variables property
+
+[Variables](https://docs.cerbos.dev/cerbos/prerelease/policies/variables.html) defined for use in conditions.
+
+**Signature:**
+
+```typescript
+variables?: Variables | undefined;
+```
+
+## Remarks
+
+Requires the Cerbos policy decision point server to be at least v0.29.
+

docs/core.principalpolicybody.version.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; [PrincipalPolicyBody](./core.principalpolicybody.md) &gt; [version](./core.principalpolicybody.version.md)
+
+## PrincipalPolicyBody.version property
+
+The version of the policy.
+
+**Signature:**
+
+```typescript
+version: string;
+```
+
+## Remarks
+
+Policies are uniquely identified by the principal name and version pair. You can have multiple policy versions for the same principal (e.g. production vs. staging). The version value `default` is special as it is the default fallback when no version is specified in the request.
+