Merge pull request #67 from cedar-policy/feature/jkastner/is_docs

Add documentation for new `is` operator

docs/collections/_other/doc-history.md

@@ -12,6 +12,7 @@ The following table describes major documentation updates for Cedar.
 
 | Description | Date |
 | --- | --- |
+| Added [`is` operator](../auth/syntax-operators.html) | December 15, 2023 |
 | Added [Entities & context syntax](../auth/entities-syntax.html) topic | July 27, 2023 |
 | Added [Schema grammar](../schema/schema-grammar.html) topic | July 17, 2023 |
 | Added [JSON policy format](../policies/json-format.html) reference page | July 14, 2023 |
@@ -23,6 +24,7 @@ The following table describes major documentation updates for Cedar.
 
 | Cedar<br/>Version | Description | Cedar SDK<br/>Versions | Date | 
 | --- |--- |--- | --- |
+| 3.0.0 | New `is` operator [PR](https://github.com/cedar-policy/cedar/pull/396) | 3.0.0 | December 15, 2023 |
 | 2.1.2 | Change to how validation treats template-linked policies [PR](https://github.com/cedar-policy/cedar/pull/371) | 2.4.2 | October 23, 2023 |
 | 2.1.1 | Increased validation precision [PR](https://github.com/cedar-policy/cedar/pull/117) | 2.4.0 - 2.4.1 | September 29, 2023 |
 | 2.1.0 | [RFC #9](https://github.com/cedar-policy/rfcs/blob/main/text/0009-disallow-whitespace-in-entityuid.md): Disallows whitespace in namespaces | 2.3.0 - 2.3.3 | June 29, 2023 |

docs/collections/_policies/json-format.md

@@ -208,6 +208,73 @@ The `op` key is required. The `op` object must have one of the following string
     },
     ```
 
+* `is`
+
+  If present, then the `principal` object must also have an `entity_type` key.
+
+  **Example**
+
+  Cedar policy line:
+
+  ```cedar
+  principal is User
+  ```
+
+  JSON representation:
+
+  ```json
+  "principal": {
+      "op": "is",
+      "entity_type": "User"
+  }
+  ```
+
+  The `principal` object may also optionally have an `in` key. The value of this key is an object with one of the following:
+
+  * [`entity`](#entity)
+
+    **Example**
+
+    Cedar policy line:
+
+    ```cedar
+    principal is User in Group::"Admins"
+    ```
+
+    JSON representation:
+
+    ```json
+    "principal": {
+        "op": "is",
+        "entity_type": "User",
+        "in": {
+            "entity": { "type": "Group", "id": "Admins" }
+        }
+    }
+    ```
+
+  * [`slot`](#slot)
+
+    **Example**
+
+    Cedar policy line:
+
+    ```cedar
+    principal is User in ?principal
+    ```
+
+    JSON representation
+
+    ```json
+    "principal": {
+        "op": "is",
+        "entity_type": "User",
+        "in": {
+            "slot": { "?principal" }
+        }
+    },
+    ```
+
 ## `action`
 
 The `action` object is required.
@@ -425,6 +492,73 @@ The `op` object must have one of the following string values:
     }
     ```
 
+* `is`
+
+  If present, then the `resource` object must also have an `entity_type` key.
+
+  **Example**
+
+  Cedar policy line:
+
+  ```cedar
+  resource is file
+  ```
+
+  JSON representation:
+
+  ```json
+  "resource": {
+      "op": "is",
+      "entity_type": "file"
+  }
+  ```
+
+  The `resource` object may also optionally have an `in` key. The value of this key is an object with one of the following:
+
+  * [`entity`](#entity)
+
+    **Example**
+
+    Cedar policy line:
+
+    ```cedar
+    resource is file in folder::"Public"
+    ```
+
+    JSON representation:
+
+    ```json
+    "resource": {
+        "op": "is",
+        "entity_type": "file",
+        "in": {
+            "entity": { "type": "Folder", "id": "Public" }
+        }
+    }
+    ```
+
+  * [`slot`](#slot)
+
+    **Example**
+
+    Cedar policy line:
+
+    ```cedar
+    resource is file in ?resource
+    ```
+
+    JSON representation
+
+    ```json
+    "resource": {
+        "op": "is",
+        "entity_type": "file",
+        "in": {
+            "slot": { "?resource" }
+        }
+    },
+    ```
+
 ## conditions
 
 The `conditions` object is required.
@@ -789,6 +923,30 @@ JSON representation
 }
 ```
 
+### `is` {#JsonExpr-is}
+
+The value of this key is an object with the keys `left` and `entity_type`.
+The `left` key is itself an [JsonExpr object](#JsonExpr-objects), while the `entity_type` key is a string.
+The value may optionally have an `in` key which is also a JsonExpr object.
+
+**Example for `is`**
+
+Cedar policy line
+
+```cedar
+principal is User in Group::"friends"
+```
+
+JSON representation
+
+```json
+"is": {
+    "left": { "Var": "principal" },
+    "entity_type": "User",
+    "in": {"entity": { "type": "Folder", "id": "Public" }}
+}
+```
+
 ### `like` {#JsonExpr-like}
 
 The value of this key is an object with keys `left` and `pattern`.  The left key is itself an [JsonExpr object](#JsonExpr-objects), while the `pattern` key is any string.

docs/collections/_policies/syntax-grammar.md

@@ -60,10 +60,12 @@ Scope ::= Principal ',' Action ',' Resource
 
 The `Principal` element consists of the `principal` keyword. If specified by itself, the policy statement matches *any* principal.
 
-Optionally, the keyword can be followed by either the [`in`](../policies/syntax-operators.html#operator-in) or [`==`](../policies/syntax-operators.html#operator-equality) operator, followed by either an `Entity`, or the `?principal` placeholder when used in a policy template.
+Optionally, the keyword can be followed by either the [`in`](../policies/syntax-operators.html#operator-in), [`==`](../policies/syntax-operators.html#operator-equality), or [`is`](../_policies/syntax-operators.html#operator-is) operator.
+An `is` operator may appear together with an `in` operators, but not an `==` operator.
+The `in` and `==` operators are followed by either an `Entity`, or the `?principal` placeholder when used in a policy template.
 
 ```
-Principal ::= 'principal' [('in' | '==') (Entity | '?principal')]
+Principal ::= 'principal' [(['is' PATH] ['in' (Entity | '?principal')]) | ('==' (Entity | '?principal'))]
 ```
 
 ## `Action` {#grammar-action}
@@ -76,10 +78,12 @@ Action ::= 'action' [( '==' Entity | 'in' ('[' EntList ']' | Entity) )]
 
 ## `Resource` {#grammar-resource}
 
-The `Resource` consists of the `resource` keyword. If specified by itself, it matches any resource. Optionally, it can be followed by either the [`in`](../policies/syntax-operators.html#operator-in) or [`==`](../policies/syntax-operators.html#operator-equality) operator, followed by an entity, or the `?resource` placeholder when used in a policy template.
+The `Resource` consists of the `resource` keyword. If specified by itself, it matches any resource. Optionally, it can be followed by either the [`in`](../policies/syntax-operators.html#operator-in), [`==`](../policies/syntax-operators.html#operator-equality), or [`is`](../_policies/syntax-operators.html#operator-is) operator.
+An `is` operator may appear together with an `in` operators, but not an `==` operator.
+The `in` and `==` operators are followed by either an `Entity`, or the `?resource` placeholder when used in a policy template.
 
 ```
-Resource ::= 'resource' [('in' | '==') (Entity | '?resource')]
+Resource ::= 'resource' [(['is' PATH] ['in' (Entity | '?resource')]) | ('==' (Entity | '?resource'))]
 ```
 
 ## `Condition` {#grammar-condition}
@@ -117,7 +121,7 @@ For more details, see [`&&` \(AND\)](../policies/syntax-operators.html#operator-
 ## `Relation` {#grammar-relation}
 
 ```
-Relation ::= Add [RELOP Add] | Add 'has' (IDENT | STR) | Add 'like' PAT
+Relation ::= Add [RELOP Add] | Add 'has' (IDENT | STR) | Add 'like' PAT | Add 'is' Path ('in' Add)?
 ```
 
 ## `Add` {#grammar-add}

docs/collections/_policies/syntax-operators.md

@@ -808,6 +808,34 @@ In that case, then the previous expression that checks for `context.addr has cou
 context has addr && context.addr has country && context.addr.country == "US"  // false, with no error
 ```
 
+### `is` \(entity type test\) {#operator-is}
+
+**Usage:** `<entity> is <entity-type>`
+
+Boolean operator that evaluates to `true` if the left operand is an entity that has the specified entity type and evaluates to `false` if the left operand is an entity that does not have the specified entity type.
+If you attempt to test the type of an expression that is not an entity, then Cedar generates an error.
+
+**Usage:** `<entity> is <entity-type> in <entity>`
+
+The `is` operator may optionally be combined with an `in` operation, in which case the expression is equivalent to `<entity> is <entity-type> && <entity> in <entity>`.
+
+**Usage:** `<entity> is <entity-type> in set(<entity>, <entity>, ...)`
+
+As when `in` appears on its own, an `is` with an `in` may check membership in a set of entities. It still may only check for one entity type.
+
+#### Examples:
+{: .no_toc }
+
+```cedar
+User::"alice" is User                       // true
+principal is User                           // true if `principal` has the `User` entity type
+principal is User in Group::"friends"       // true if `principal` has the `User` entity type and is in `Group::"friends"`
+ExampleCo::User::"alice" is ExampleCo::User // true
+Group::"friends" is User                    // false
+ExampleCo::User::"alice" is User            // false - `ExampleCo::User` and `User` are different entity types
+"alice" is String                           // type error - `is` only applies to entities
+```
+
 ### `.contains()` \(single element set membership test\) {#function-contains}
 
 **Usage:** `<set>.contains(<entity>)`

docs/collections/_policies/syntax-policy.md

@@ -114,6 +114,12 @@ principal == User::"alice"
 
 //matches any principal in the hierarchy of the specified Group
 principal in Group::"alice_friends"
+
+//matches any principal of type User
+principal is User
+
+//matches any principal of type User in the hierarchy of the specified Group
+principal is User in Group::"alice_friends"
 ```
 
 ### `action` {#term-parc-action}
@@ -157,6 +163,12 @@ resource == Photo::"VacationPhoto94.jpg"
 
 //matches any resource that is in the hierarchy of the specified entity of type Album
 resource in Album::"alice_vacation"
+
+//matches any resource of type Photo
+resource is Photo
+
+//matches any resource of type Photo in the hierarchy of the specified entity Album
+resource is Photo in Album::"alice_vacation"
 ```
 
 ## Conditions {#term-parc-context}

docs/collections/_policies/templates.md

@@ -17,6 +17,7 @@ You can use placeholders in a Cedar policy template for only the following two e
 You can use either one or both in a policy template.
 
 Placeholders can appear in ***only*** the policy head on the right-hand side of the `==` or `in` operators.
+This includes `in` operators when appearing together with an `is` operator, but excludes solitary `is` operators.
 
 Then, when you create a policy based on the policy template, you must specify values for each of the placeholders. Those values are combined with the rest of the policy template to form a complete and usable template-linked policy.
 

docs/collections/_policies/validation.md

@@ -117,6 +117,7 @@ The validator compares a policy with a schema to look for inconsistencies. From
 + **Unsafe access to optional attributes** – For example, `principal.numberOfLaptops` where `numberOfLaptops` is an optional attribute declared with `"required": false`. Such tests should be guarded by including a [`has`](../policies/syntax-operators.html#operator-has) check as the left side of the shortcut [&&](../policies/syntax-operators.html#operator-and) expression. For example, as in `principal has numberOfLaptops && principal.numberOfLaptops > 1`.
 + **Type mismatch in operators** – For example, `principal.jobLevel > "14"` is an illegal comparison with a `String`.
 + **Cases that always evaluate to false, and thus never apply** – For example, `when { principal has manager && principal.manager == User::"Ethel" }` always evaluates to `false` when the type of `principal` will never have the `manager` attribute, as made clear in the schema, so the policy can never apply.
+  Similarly, `principal is ExampleCo::Personnel::Admin` always evaluates to `false` when the `principal` is always a `User`, and not an `Admin`.
 
 The schema can also specify the expected format of the context record for each `Action`. Making this specification lets Cedar also flag errors on references to context.