From 597506306737a00bd594e4da7c30ecc6de4b1f8e Mon Sep 17 00:00:00 2001 From: Andrew Haines Date: Thu, 13 Jul 2023 15:48:44 +0100 Subject: [PATCH] Support `exportVariables` policies Signed-off-by: Andrew Haines --- docs/core.derivedroles.derivedroles.md | 1 + docs/core.derivedroles.md | 2 +- docs/core.exportvariables.exportvariables.md | 16 +++++++++ docs/core.exportvariables.md | 25 +++++++++++++ docs/core.md | 3 ++ docs/core.policy.md | 4 +-- docs/core.policybase.variables.md | 5 +++ docs/core.policyisexportvariables.md | 13 +++++++ docs/core.principalpolicy.md | 2 +- docs/core.principalpolicy.principalpolicy.md | 1 + docs/core.resourcepolicy.md | 2 +- docs/core.resourcepolicy.resourcepolicy.md | 1 + docs/core.variables.import.md | 13 +++++++ docs/core.variables.local.md | 13 +++++++ docs/core.variables.md | 21 +++++++++++ package.json | 2 +- packages/core/CHANGELOG.md | 4 +++ packages/core/src/convert/fromProtobuf.ts | 31 ++++++++++++++++ packages/core/src/convert/toProtobuf.ts | 36 +++++++++++++++++-- .../core/src/types/external/DerivedRoles.ts | 9 +++++ .../src/types/external/ExportVariables.ts | 27 ++++++++++++++ packages/core/src/types/external/Policy.ts | 16 ++++++++- .../core/src/types/external/PolicyBase.ts | 2 ++ .../src/types/external/PrincipalPolicy.ts | 9 +++++ .../core/src/types/external/ResourcePolicy.ts | 9 +++++ packages/core/src/types/external/Variables.ts | 16 +++++++++ packages/core/src/types/external/index.ts | 2 ++ packages/grpc/CHANGELOG.md | 4 +++ packages/http/CHANGELOG.md | 4 +++ 29 files changed, 284 insertions(+), 9 deletions(-) create mode 100644 docs/core.exportvariables.exportvariables.md create mode 100644 docs/core.exportvariables.md create mode 100644 docs/core.policyisexportvariables.md create mode 100644 docs/core.variables.import.md create mode 100644 docs/core.variables.local.md create mode 100644 docs/core.variables.md create mode 100644 packages/core/src/types/external/ExportVariables.ts create mode 100644 packages/core/src/types/external/Variables.ts diff --git a/docs/core.derivedroles.derivedroles.md b/docs/core.derivedroles.derivedroles.md index 25bcfc4e..f8522460 100644 --- a/docs/core.derivedroles.derivedroles.md +++ b/docs/core.derivedroles.derivedroles.md @@ -12,5 +12,6 @@ A set of derived roles. derivedRoles: { name: string; definitions: DerivedRoleDefinition[]; + variables?: Variables | undefined; }; ``` diff --git a/docs/core.derivedroles.md b/docs/core.derivedroles.md index a185ba66..098e9dd8 100644 --- a/docs/core.derivedroles.md +++ b/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. | diff --git a/docs/core.exportvariables.exportvariables.md b/docs/core.exportvariables.exportvariables.md new file mode 100644 index 00000000..9cc25c93 --- /dev/null +++ b/docs/core.exportvariables.exportvariables.md @@ -0,0 +1,16 @@ + + +[Home](./index.md) > [@cerbos/core](./core.md) > [ExportVariables](./core.exportvariables.md) > [exportVariables](./core.exportvariables.exportvariables.md) + +## ExportVariables.exportVariables property + +A set of exported variables. + +**Signature:** + +```typescript +exportVariables: { + name: string; + definitions: Record; + }; +``` diff --git a/docs/core.exportvariables.md b/docs/core.exportvariables.md new file mode 100644 index 00000000..87dff679 --- /dev/null +++ b/docs/core.exportvariables.md @@ -0,0 +1,25 @@ + + +[Home](./index.md) > [@cerbos/core](./core.md) > [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<string, string>; } | A set of exported variables. | + diff --git a/docs/core.md b/docs/core.md index 607b6df9..1bb5972b 100644 --- a/docs/core.md +++ b/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). | diff --git a/docs/core.policy.md b/docs/core.policy.md index 8e813dd2..909ddf08 100644 --- a/docs/core.policy.md +++ b/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) diff --git a/docs/core.policybase.variables.md b/docs/core.policybase.variables.md index 5f9a1c60..f8e8d136 100644 --- a/docs/core.policybase.variables.md +++ b/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:** diff --git a/docs/core.policyisexportvariables.md b/docs/core.policyisexportvariables.md new file mode 100644 index 00000000..bd52cea9 --- /dev/null +++ b/docs/core.policyisexportvariables.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@cerbos/core](./core.md) > [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 +``` diff --git a/docs/core.principalpolicy.md b/docs/core.principalpolicy.md index 6b6ee8cf..6804762c 100644 --- a/docs/core.principalpolicy.md +++ b/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. | diff --git a/docs/core.principalpolicy.principalpolicy.md b/docs/core.principalpolicy.principalpolicy.md index b470a23f..5dbc796b 100644 --- a/docs/core.principalpolicy.principalpolicy.md +++ b/docs/core.principalpolicy.principalpolicy.md @@ -14,5 +14,6 @@ principalPolicy: { version: string; rules: PrincipalRule[]; scope?: string; + variables?: Variables | undefined; }; ``` diff --git a/docs/core.resourcepolicy.md b/docs/core.resourcepolicy.md index 60086c1f..a9ae4cf7 100644 --- a/docs/core.resourcepolicy.md +++ b/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. | diff --git a/docs/core.resourcepolicy.resourcepolicy.md b/docs/core.resourcepolicy.resourcepolicy.md index a6c02662..2c1fc800 100644 --- a/docs/core.resourcepolicy.resourcepolicy.md +++ b/docs/core.resourcepolicy.resourcepolicy.md @@ -16,5 +16,6 @@ resourcePolicy: { rules: ResourceRule[]; scope?: string; schemas?: SchemaRefs | undefined; + variables?: Variables | undefined; }; ``` diff --git a/docs/core.variables.import.md b/docs/core.variables.import.md new file mode 100644 index 00000000..cf46da52 --- /dev/null +++ b/docs/core.variables.import.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@cerbos/core](./core.md) > [Variables](./core.variables.md) > [import](./core.variables.import.md) + +## Variables.import property + +Names of variable sets to import. + +**Signature:** + +```typescript +import?: string[]; +``` diff --git a/docs/core.variables.local.md b/docs/core.variables.local.md new file mode 100644 index 00000000..fe0505d7 --- /dev/null +++ b/docs/core.variables.local.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@cerbos/core](./core.md) > [Variables](./core.variables.md) > [local](./core.variables.local.md) + +## Variables.local property + +Variable expressions defined for the policy. + +**Signature:** + +```typescript +local?: Record; +``` diff --git a/docs/core.variables.md b/docs/core.variables.md new file mode 100644 index 00000000..ae8739c8 --- /dev/null +++ b/docs/core.variables.md @@ -0,0 +1,21 @@ + + +[Home](./index.md) > [@cerbos/core](./core.md) > [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<string, string> | _(Optional)_ Variable expressions defined for the policy. | + diff --git a/package.json b/package.json index 1a51bb16..a33dc674 100644 --- a/package.json +++ b/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", diff --git a/packages/core/CHANGELOG.md b/packages/core/CHANGELOG.md index e4dfdf83..e1d5a7ce 100644 --- a/packages/core/CHANGELOG.md +++ b/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 diff --git a/packages/core/src/convert/fromProtobuf.ts b/packages/core/src/convert/fromProtobuf.ts index 870570ab..21db5b89 100644 --- a/packages/core/src/convert/fromProtobuf.ts +++ b/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: { 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: { + name, + definitions, + }, +}); + const principalPolicyFromProtobuf = ({ principal, version, rules, scope, + variables, }: PrincipalPolicyProtobuf): OmitPolicyBase => ({ 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: { resource, @@ -358,6 +388,7 @@ const resourcePolicyFromProtobuf = ({ rules: rules.map(resourceRuleFromProtobuf), schemas: schemas && schemaRefsFromProtobuf(schemas), scope, + variables: variables && variablesFromProtobuf(variables), }, }); diff --git a/packages/core/src/convert/toProtobuf.ts b/packages/core/src/convert/toProtobuf.ts index 46a340ad..fdf832bb 100644 --- a/packages/core/src/convert/toProtobuf.ts +++ b/packages/core/src/convert/toProtobuf.ts @@ -9,6 +9,7 @@ import type { import type { Condition as ConditionProtobuf, DerivedRoles as DerivedRolesProtobuf, + ExportVariables as ExportVariablesProtobuf, Match as MatchProtobuf, Match_ExprList, Output as OutputProtobuf, @@ -21,6 +22,7 @@ import type { RoleDef, Schemas, Schemas_Schema, + Variables as VariablesProtobuf, } from "../protobuf/cerbos/policy/v1/policy"; import type { AddOrUpdatePolicyRequest, @@ -48,6 +50,7 @@ import type { DerivedRoleDefinition, DerivedRoles, EnablePoliciesRequest, + ExportVariables, GetPoliciesRequest, JWT, ListPoliciesRequest, @@ -69,6 +72,7 @@ import type { SchemaInput, SchemaRef, SchemaRefs, + Variables, } from "../types/external"; import { Effect, @@ -78,6 +82,7 @@ import { matchIsMatchExpr, matchIsMatchNone, policyIsDerivedRoles, + policyIsExportVariables, policyIsPrincipalPolicy, policyIsResourcePolicy, } from "../types/external"; @@ -104,6 +109,7 @@ const policyToProtobuf = (policy: Policy): PolicyProtobuf => { apiVersion, description, disabled, + jsonSchema: "", metadata: undefined, policyType: policyTypeToProtobuf(policy), variables, @@ -120,6 +126,13 @@ const policyTypeToProtobuf = ( }; } + if (policyIsExportVariables(policy)) { + return { + $case: "exportVariables", + exportVariables: exportVariablesToProtobuf(policy), + }; + } + if (policyIsPrincipalPolicy(policy)) { return { $case: "principalPolicy", @@ -138,10 +151,11 @@ const policyTypeToProtobuf = ( }; const derivedRolesToProtobuf = ({ - derivedRoles: { name, definitions }, + derivedRoles: { name, definitions, variables }, }: DerivedRoles): DerivedRolesProtobuf => ({ name, definitions: definitions.map(derivedRoleDefinitionToProtobuf), + variables: variables && variablesToProtobuf(variables), }); const derivedRoleDefinitionToProtobuf = ({ @@ -205,13 +219,29 @@ const matchesToProtobuf = ({ of }: Matches): Match_ExprList => ({ of: of.map(matchToProtobuf), }); +const variablesToProtobuf = ({ + import: imports = [], + local = {}, +}: Variables): VariablesProtobuf => ({ + import: imports, + local, +}); + +const exportVariablesToProtobuf = ({ + exportVariables: { name, definitions }, +}: ExportVariables): ExportVariablesProtobuf => ({ + name, + definitions, +}); + const principalPolicyToProtobuf = ({ - principalPolicy: { principal, version, rules, scope = "" }, + principalPolicy: { principal, version, rules, scope = "", variables }, }: PrincipalPolicy): PrincipalPolicyProtobuf => ({ principal, version, rules: rules.map(principalRuleToProtobuf), scope, + variables: variables && variablesToProtobuf(variables), }); const principalRuleToProtobuf = ({ @@ -251,6 +281,7 @@ const resourcePolicyToProtobuf = ({ rules, scope = "", schemas, + variables, }, }: ResourcePolicy): ResourcePolicyProtobuf => ({ resource, @@ -259,6 +290,7 @@ const resourcePolicyToProtobuf = ({ rules: rules.map(resourceRuleToProtobuf), scope, schemas: schemas && policySchemasToProtobuf(schemas), + variables: variables && variablesToProtobuf(variables), }); const resourceRuleToProtobuf = ({ diff --git a/packages/core/src/types/external/DerivedRoles.ts b/packages/core/src/types/external/DerivedRoles.ts index c56edbab..22b01ee1 100644 --- a/packages/core/src/types/external/DerivedRoles.ts +++ b/packages/core/src/types/external/DerivedRoles.ts @@ -1,5 +1,6 @@ import type { DerivedRoleDefinition } from "./DerivedRoleDefinition"; import type { PolicyBase } from "./PolicyBase"; +import type { Variables } from "./Variables"; /** * A set of {@link https://docs.cerbos.dev/cerbos/latest/policies/derived_roles.html | derived roles} @@ -21,5 +22,13 @@ export interface DerivedRoles extends PolicyBase { * The definitions of the derived roles. */ definitions: DerivedRoleDefinition[]; + + /** + * {@link https://docs.cerbos.dev/cerbos/prerelease/policies/variables.html | Variables} defined for use in conditions. + * + * @remarks + * Requires the Cerbos policy decision point server to be at least v0.29. + */ + variables?: Variables | undefined; }; } diff --git a/packages/core/src/types/external/ExportVariables.ts b/packages/core/src/types/external/ExportVariables.ts new file mode 100644 index 00000000..8f78041a --- /dev/null +++ b/packages/core/src/types/external/ExportVariables.ts @@ -0,0 +1,27 @@ +import type { PolicyBase } from "./PolicyBase"; + +/** + * A set of {@link https://docs.cerbos.dev/cerbos/prerelease/policies/variables.html#export | exported variables} + * to be reused in other policies. + * + * @remarks + * Requires the Cerbos policy decision point server to be at least v0.29. + * + * @public + */ +export interface ExportVariables extends PolicyBase { + /** + * A set of exported variables. + */ + exportVariables: { + /** + * The name to use when importing the set of variables. + */ + name: string; + + /** + * Variable expressions. + */ + definitions: Record; + }; +} diff --git a/packages/core/src/types/external/Policy.ts b/packages/core/src/types/external/Policy.ts index 7b733ccc..1bf537ca 100644 --- a/packages/core/src/types/external/Policy.ts +++ b/packages/core/src/types/external/Policy.ts @@ -1,4 +1,5 @@ import type { DerivedRoles } from "./DerivedRoles"; +import type { ExportVariables } from "./ExportVariables"; import type { PrincipalPolicy } from "./PrincipalPolicy"; import type { ResourcePolicy } from "./ResourcePolicy"; @@ -7,7 +8,11 @@ import type { ResourcePolicy } from "./ResourcePolicy"; * * @public */ -export type Policy = DerivedRoles | PrincipalPolicy | ResourcePolicy; +export type Policy = + | DerivedRoles + | ExportVariables + | PrincipalPolicy + | ResourcePolicy; /** * Type guard to check if a {@link Policy} is a set of {@link DerivedRoles}. @@ -17,6 +22,15 @@ export type Policy = DerivedRoles | PrincipalPolicy | ResourcePolicy; export const policyIsDerivedRoles = (policy: Policy): policy is DerivedRoles => "derivedRoles" in policy; +/** + * Type guard to check if a {@link Policy} is a set of {@link ExportVariables}. + * + * @public + */ +export const policyIsExportVariables = ( + policy: Policy, +): policy is ExportVariables => "exportVariables" in policy; + /** * Type guard to check if a {@link Policy} is a {@link PrincipalPolicy}. * diff --git a/packages/core/src/types/external/PolicyBase.ts b/packages/core/src/types/external/PolicyBase.ts index 7cd682e8..f3a1b86e 100644 --- a/packages/core/src/types/external/PolicyBase.ts +++ b/packages/core/src/types/external/PolicyBase.ts @@ -32,6 +32,8 @@ export interface PolicyBase { * @remarks * Each variable is evaluated before any rule condition. * A variable expression can contain anything that condition expression can have. + * + * @deprecated Define variables within the policy body instead (provided the Cerbos policy decision point server is at least v0.29). */ variables?: Record; } diff --git a/packages/core/src/types/external/PrincipalPolicy.ts b/packages/core/src/types/external/PrincipalPolicy.ts index a80b906a..f1cf0dd0 100644 --- a/packages/core/src/types/external/PrincipalPolicy.ts +++ b/packages/core/src/types/external/PrincipalPolicy.ts @@ -1,5 +1,6 @@ import type { PolicyBase } from "./PolicyBase"; import type { PrincipalRule } from "./PrincipalRule"; +import type { Variables } from "./Variables"; /** * A {@link https://docs.cerbos.dev/cerbos/latest/policies/principal_policies.html | policy} defining overrides for a specific user. @@ -35,5 +36,13 @@ export interface PrincipalPolicy extends PolicyBase { * {@link https://docs.cerbos.dev/cerbos/latest/policies/scoped_policies.html | Scope} of the policy. */ scope?: string; + + /** + * {@link https://docs.cerbos.dev/cerbos/prerelease/policies/variables.html | Variables} defined for use in conditions. + * + * @remarks + * Requires the Cerbos policy decision point server to be at least v0.29. + */ + variables?: Variables | undefined; }; } diff --git a/packages/core/src/types/external/ResourcePolicy.ts b/packages/core/src/types/external/ResourcePolicy.ts index bce0b5b8..7ff39f00 100644 --- a/packages/core/src/types/external/ResourcePolicy.ts +++ b/packages/core/src/types/external/ResourcePolicy.ts @@ -1,6 +1,7 @@ import type { PolicyBase } from "./PolicyBase"; import type { ResourceRule } from "./ResourceRule"; import type { SchemaRefs } from "./SchemaRefs"; +import type { Variables } from "./Variables"; /** * A {@link https://docs.cerbos.dev/cerbos/latest/policies/resource_policies.html | policy} defining rules for actions that can be performed on a given resource. @@ -46,5 +47,13 @@ export interface ResourcePolicy extends PolicyBase { * {@link https://docs.cerbos.dev/cerbos/latest/policies/schemas.html | Schemas} for principal and resource attributes. */ schemas?: SchemaRefs | undefined; + + /** + * {@link https://docs.cerbos.dev/cerbos/prerelease/policies/variables.html | Variables} defined for use in conditions. + * + * @remarks + * Requires the Cerbos policy decision point server to be at least v0.29. + */ + variables?: Variables | undefined; }; } diff --git a/packages/core/src/types/external/Variables.ts b/packages/core/src/types/external/Variables.ts new file mode 100644 index 00000000..ba33afe4 --- /dev/null +++ b/packages/core/src/types/external/Variables.ts @@ -0,0 +1,16 @@ +/** + * {@link https://docs.cerbos.dev/cerbos/prerelease/policies/variables.html | Variables} defined for use in policy conditions. + * + * @public + */ +export interface Variables { + /** + * Names of variable sets to import. + */ + import?: string[]; + + /** + * Variable expressions defined for the policy. + */ + local?: Record; +} diff --git a/packages/core/src/types/external/index.ts b/packages/core/src/types/external/index.ts index 914ff703..2a0514f4 100644 --- a/packages/core/src/types/external/index.ts +++ b/packages/core/src/types/external/index.ts @@ -18,6 +18,7 @@ export * from "./DisablePoliciesResponse"; export * from "./Effect"; export * from "./EnablePoliciesRequest"; export * from "./EnablePoliciesResponse"; +export * from "./ExportVariables"; export * from "./GetPoliciesRequest"; export * from "./GetPoliciesResponse"; export * from "./GetSchemasRequest"; @@ -71,3 +72,4 @@ export * from "./ValidationError"; export * from "./ValidationErrorSource"; export * from "./ValidationFailedCallback"; export * from "./Value"; +export * from "./Variables"; diff --git a/packages/grpc/CHANGELOG.md b/packages/grpc/CHANGELOG.md index bd4e16a1..e23ba57b 100644 --- a/packages/grpc/CHANGELOG.md +++ b/packages/grpc/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+. + ### Changed - Bump dependency on [@grpc/grpc-js](https://github.com/grpc/grpc-node) to 1.8.17 ([#555](https://github.com/cerbos/cerbos-sdk-javascript/pull/555), [#575](https://github.com/cerbos/cerbos-sdk-javascript/pull/575), [#578](https://github.com/cerbos/cerbos-sdk-javascript/pull/578)) diff --git a/packages/http/CHANGELOG.md b/packages/http/CHANGELOG.md index 5c03a249..1a143764 100644 --- a/packages/http/CHANGELOG.md +++ b/packages/http/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.12.0] - 2023-06-07 ### Added