diff --git a/pages/spicedb/concepts/caveats.mdx b/pages/spicedb/concepts/caveats.mdx index ddc3f80..5b75bfc 100644 --- a/pages/spicedb/concepts/caveats.mdx +++ b/pages/spicedb/concepts/caveats.mdx @@ -117,21 +117,31 @@ A few important notes: Otherwise, the values in the `Relationship` take precedence over those in the `CheckPermissionRequest`. - Context of a caveat provided in `Relationship` is stored alongside the relationship and is provided to the caveat expression at runtime. This allows for **partial** binding of data at write time. -- The Context is a `structpb`, which is defined by Google and represents JSON-like data: [https://pkg.go.dev/google.golang.org/protobuf/types/known/structpb](https://pkg.go.dev/google.golang.org/protobuf/types/known/structpb) +- The Context is a `structpb`, which is defined by Google [and represents JSON-like data](https://pkg.go.dev/google.golang.org/protobuf/types/known/structpb). - To send 64-bit integers, encode them as strings. - A relationship cannot be duplicated, with or without a caveat, e.g. two relationships that differ only on their use of a caveat cannot both exist. - When deleting a relationship, a caveat does not need to be specified; the matching relationship will be deleted if present. -## Issuing Checks +## Providing Caveat Context via the API + +### `CheckPermission` When issuing a [CheckPermission request][check-req], additional caveat context can be specified to represent the known context at the time of the check: ```textproto CheckPermissionRequest { - Resource: …, - Permission: …, - Subject: …, - Context: { "user_ip": "1.2.3.4" } + resource: { + object_type: "book", + object_id: "specificbook", + }, + permission: "view", + subject: { + object: { + object_type: "user", + object_id: "specificuser", + }, + }, + context: { "user_ip": "1.2.3.4" } } ``` @@ -147,10 +157,56 @@ In the case of `PERMISSIONSHIP_CONDITIONAL_PERMISSION`, SpiceDB will also return [states]: https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.CheckPermissionResponse.Permissionship [check-resp]: https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.CheckPermissionResponse -## LookupResources and LookupSubjects +## `LookupResources` and `LookupSubjects` Similarly to **CheckPermission**, both **LookupResources** and **LookupSubjects** can be provided with additional context and will return one of the two permission states for each of the results found (either has permission or conditionally has permission). +```textproto +LookupResourcesRequest { + resource_object_type: "book", + permission: "view", + subject: { + object: { + object_type: "user", + object_id: "specificuser", + }, + }, + context: { "user_ip": "1.2.3.4" } +} +``` + +### Providing Caveat Context with `zed CLI + +When using `zed` command-line tool to interact with SpiceDB, the context can be provided using the `--caveat-context` flag. +The caveat context should be a JSON representation that matches the types defined in the schema. +For example, with the following caveat: + +```zed +caveat first_caveat(first_parameter int, second_parameter string) { + first_parameter == 42 && second_parameter == "hello world" +} +``` + +We would need to forward a JSON object like: + +```json +{ + "first_parameter": 42, + "second_parameter": "hello world" +} +``` + +The full command would look like: + +```shell +zed check -r resource:specificresource#view -p view -s user:specificuser --caveat-context '{"first_parameter": 42, "second_parameter": "hello world"}' +``` + + + Please note the use of single quotes to escape the characters in the JSON representation of the context. + You don't need character escaping when providing context using zed in the Authzed Playground. + + ## Full Example A full example of a schema with caveats can be found below, which allows users to `view` a resource if they are directly a `viewer` or they are a`viewer` within the correct IP CIDR range: diff --git a/pages/spicedb/modeling/validation-testing-debugging.mdx b/pages/spicedb/modeling/validation-testing-debugging.mdx index b581bb5..fe8b50f 100644 --- a/pages/spicedb/modeling/validation-testing-debugging.mdx +++ b/pages/spicedb/modeling/validation-testing-debugging.mdx @@ -57,6 +57,29 @@ assertTrue: assertFalse: [] ``` +#### Caveat Context In Assertions + + + In order to escape JSON representation of the caveat context in an assertion you should use single-quotes + + +You can provide caveat context as part of an assertion: + +```yaml +assertTrue: + - 'document:validation-testing-debugging#reader@user:you with {"somecondition": 42, "anothercondition": "hello world"}' +assertFalse: [] +``` + +You can also assert that a caveat context is required for a particular expression using `assertCaveated`: + +```yaml +assertTrue: [] +assertCaveated: + - "document:validation-testing-debugging#reader@user:you" +assertFalse: [] +``` + ### Check Watches Check Watches are type of assertion that updates in real-time with changes in the Playground. @@ -67,6 +90,15 @@ Below is an example of configuring a Check Watch:
+Watches can show any of the following states: + +- ✅ Permission Allowed +- ❔ Permission Caveated +- ❌ Permission Denied +- ⚠️ Invalid Check + +![check-watches](/images/check-watches.png) + ### Expected Relations Expected Relations are a type of assertion that can be used to enumerate access to a specific relation. @@ -88,6 +120,33 @@ project:docs#admin: - "[user:rauchg] is " ``` +### Caveats in Expected Relations + +When caveats are involved, and due to the unbounded nature of it, the Playground will focus on enumerating +expected relations with "maybe" semantics. +You can't specify an expected relation with a specific caveat context, because the Playground supports inferring those for you, +and that would lead potentially to an infinite number of possible caveat context values. + +What you'll see is an expected relation with the caveat context denoted as `[...]` right after the resource. +This reads as `user:rauchg may have admin permission over platform vercel`. + +```yaml +project:docs#admin: + - "[user:rauchg[...]] is " +``` + +### Exceptions in Expected Relations + +There are also scenarios where an expected relation is described with an exception, which indicates that a permission +holds for a specific resource and subject pair, but with a potential exception. + +The following example reads like: `user:rauchg has admin permission over platform vercel, unless user:rauchg is banned`. + +```yaml +project:docs#admin: + - "[user:rauchg[...]] is /" +``` + ## Check Tracing SpiceDB supports tracing of check requests to view the path(s) taken to compute the result, as well as timing information. diff --git a/public/images/check-watches.png b/public/images/check-watches.png new file mode 100644 index 0000000..ceb3602 Binary files /dev/null and b/public/images/check-watches.png differ