You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: pages/spicedb/concepts/caveats.mdx
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -119,7 +119,7 @@ A few important notes:
119
119
This allows for **partial** binding of data at write time.
120
120
- 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).
121
121
- To send 64-bit integers, encode them as strings.
122
-
- 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.
122
+
- A relationship cannot be duplicated, with or without a caveat. In other words, two relationships that differ only on their use of a caveat cannot both exist.
123
123
- When deleting a relationship, a caveat does not need to be specified; the matching relationship will be deleted if present.
124
124
125
125
## Providing Caveat Context via the API
@@ -157,7 +157,7 @@ In the case of `PERMISSIONSHIP_CONDITIONAL_PERMISSION`, SpiceDB will also return
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).
163
163
@@ -175,7 +175,7 @@ LookupResourcesRequest {
175
175
}
176
176
```
177
177
178
-
###Providing Caveat Context with `zed CLI
178
+
## Providing Caveat Context with `zed CLI`
179
179
180
180
When using `zed` command-line tool to interact with SpiceDB, the context can be provided using the `--caveat-context` flag.
181
181
The caveat context should be a JSON representation that matches the types defined in the schema.
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:
212
+
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 if they are a`viewer` within the correct IP CIDR range:
Copy file name to clipboardExpand all lines: pages/spicedb/concepts/expiring-relationships.mdx
+9-5Lines changed: 9 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,14 +11,18 @@ import { InlinePlayground } from '@/components/playground';
11
11
A common use case is to model relationships that expire after a certain time.
12
12
This is useful for granting temporary access to a resource.
13
13
14
-
Until now, caveats were the recommended way to support time-bound permissions, but that has some limitations:
14
+
Before version 1.40, [caveats] were the recommended way to support time-bound permissions, but that has some limitations:
15
+
16
+
[caveats]: caveats
15
17
16
18
- It requires clients to provide the `now` timestamp.
17
19
This is additional complexity for clients.
18
20
- Expired caveats are not automatically garbage collected.
19
21
This can lead to many caveated relationships in the system and increase the costs of loading and evaluating those into the runtime.
20
22
21
-
SpiceDB supports expiring relationships, which lets users define relationships that expire at a given time.
23
+
SpiceDB supports expiring relationships, which lets users define relationships that expire at a given time. The time must be specified in [RFC 3339 format].
Copy file name to clipboardExpand all lines: pages/spicedb/concepts/schema.mdx
+9-10Lines changed: 9 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -77,7 +77,7 @@ definition document {
77
77
```
78
78
79
79
<Callouttype="info">
80
-
In the above example, the `user` on `reader` does not contain a sub-relation
80
+
In the above example, the `user` on `reader` does not contain a sub-relation.
81
81
82
82
Occasionally you will see a subject which has a sub-relation such as `usergroup:admins#members` which refers not just to the `usergroup` as a whole, but the set of members which have that relation to the `usergroup`.
83
83
@@ -181,7 +181,7 @@ Permissions support four kinds of operations: **union**, **intersection**, **exc
181
181
182
182
#### `+` (Union)
183
183
184
-
Unions together the relations/permissions referenced
184
+
Unions together the relations/permissions referenced.
185
185
186
186
Union is the most common operation and is used to join different relations or permissions together to form a set of allowed subjects.
Arrows allow for "walking" the heirarchy of relations (and permissions) defined for an **object** of a subject, referencing a permission or relation on the _resulting_ subject's object.
220
+
Arrows allow for "walking" the hierarchy of relations (and permissions) defined for an **object** of a subject, referencing a permission or relation on the _resulting_ subject's object.
221
221
222
222
For example, imagine a schema where a document is found under a folder:
223
223
@@ -260,7 +260,7 @@ definition document {
260
260
261
261
The expression `parent_folder->read` indicates to "walk" from the `parent_folder` of the `document`, and then to include the subjects found for the `read` permission of that folder.
262
262
263
-
Making use of a `union`, we can also include the local `reader` relation, allowing the `read` permission on a document can check whether a user is a `reader` of a document or a `reader` of its parent folder.
263
+
Making use of a `union`, we can also include the local `reader` relation, allowing the `read` permission on a document to check whether a user is a `reader` of a document or a `reader` of its parent folder.
264
264
265
265
```zed
266
266
definition user {}
@@ -298,7 +298,7 @@ definition document {
298
298
For example, in:
299
299
300
300
```
301
-
defintion resource {
301
+
definition resource {
302
302
relation parent: group#member
303
303
permission someperm = parent->something
304
304
}
@@ -379,7 +379,6 @@ In the above example, the user must be in the `member` relation for _all_ groups
379
379
380
380
<Callouttype="warning">
381
381
Intersection arrows can impact performance since they require loading **all** results for the arrow. This is especially a concern for arrows that traverse relationship graphs with a high branching factor.
382
-
results for the arrow, it can impact performance if the arrow is very wide.
383
382
</Callout>
384
383
385
384
### Naming Permissions
@@ -455,7 +454,7 @@ Admin permission on resources is then defined as the direct owner of the resourc
455
454
456
455
Relation traversals can be modeled using intermediate, synthetic relations.
457
456
458
-
Given the example hierarchy, portfolio can have folders, folders can have documents, we’d like a viewer of a portfolio to also be able to read documents contained in its folders.
457
+
Given the example hierarchy below, where a portfolio can have folders and folders can have documents, we’d like a viewer of a portfolio to also be able to read documents contained in its folders.
Copy file name to clipboardExpand all lines: pages/spicedb/concepts/watch.mdx
+2-1Lines changed: 2 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,12 +5,13 @@ import { InlinePlayground } from '@/components/playground';
5
5
6
6
The [Watch API] in SpiceDB enables clients to monitor changes made to [Relationships] within the system.
7
7
8
-
Watch events are generated when relationships are created, touched, or deleted through the [WriteRelationships], [DeleteRelationships], or the bulk import API.
8
+
Watch events are generated when relationships are created, touched, or deleted through the [WriteRelationships], [DeleteRelationships] or [BulkImportRelationships] APIs.
Copy file name to clipboardExpand all lines: pages/spicedb/concepts/zanzibar.mdx
+9-8Lines changed: 9 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -33,7 +33,7 @@ In homeage, AuthZed maintained a Dune-related naming scheme for their own projec
33
33
### Popularizing ReBAC
34
34
35
35
**Re**lationship-**b**ased **A**ccess **C**ontrol (ReBAC) is a one of the paradigms for the design of authorization systems.
36
-
The core idea behind ReBAC is that the existence of a chain relationships between a subject and a resource defines access.
36
+
The core idea behind ReBAC is that the existence of a chain of relationships between a subject and a resource defines access.
37
37
This abstraction alone is able to model all other existing authorization paradigms including the very popular RBAC and ABAC designs.
38
38
The concept was originally described by Carrie Gates in a 2006 paper entitled [Access Control Requirements for Web 2.0 Security and Privacy][web2-paper] with Facebook cited as an early adopter of this paradigm.
39
39
However, it wouldn't be until the publication of the Zanzibar paper in 2019 that ReBAC would achieve popularity outside of applications that weren't already leveraging graph abstractions for their data.
@@ -49,10 +49,10 @@ For more information on ReBAC, see the [documentation for Relationships][rels].
49
49
50
50
### New Enemy Problem
51
51
52
-
The New Enemy Problem is scenario where unauthorized access can occur when changes to permissions and the resources they protect are not updated together [consistently].
52
+
The New Enemy Problem is a scenario where unauthorized access can occur when changes to permissions and the resources they protect are not updated together [consistently].
53
53
SpiceDB solves this problem with configurable consistency and ZedTokens, its version of Zookies.
54
54
55
-
This term was first introduced in the Zanzibar paper where solving this problem was a fundamental design goal:
55
+
The term "Zookies" was first introduced in the Zanzibar paper where solving this problem was a fundamental design goal:
56
56
57
57
>ACL checks must respect the order in which users modify ACLs and object contents to avoid unexpected sharing behaviors.
58
58
>Specifically, our clients care about preventing the "new enemy" problem, which can arise when we fail to respect the ordering between ACL updates or when we apply old ACLs to new content.
@@ -110,9 +110,9 @@ SpiceDB instead offers a [Schema Language][schema] that internally compiles into
110
110
111
111
Zanzibar [does not disambiguate][disambiguate] between relations that define access and those that exist purely in the abstract.
112
112
113
-
SpiceDB introduces new terms and syntax to differentiate relations into two concepts Relations and Permissions.
113
+
SpiceDB introduces new terms and syntax to differentiate relations into two concepts: Relations and Permissions.
114
114
115
-
Permissions are best thought of "public API" being consumed by applications to check access.
115
+
Permissions are best thought of as the "public API" being consumed by applications to check access.
116
116
Permissions are defined using set semantics referred to in Zanzibar parlance as
117
117
"computed usersets".
118
118
@@ -141,19 +141,20 @@ Zanzibar only supports Google's internal [Spanner] service for tuple-storage.
141
141
142
142
SpiceDB supports a variety of datastores; including [Cloud Spanner].
143
143
144
-
You can learn more about datastores in the [Datastore documentation].
144
+
You can learn more about datastores in the [Datastores documentation].
Zanzibar supports a [ContentChangeCheck API][ccc-api] and the ability specify "at least as fresh" as a Zookie.
152
+
Zanzibar supports a [ContentChangeCheck API][ccc-api] and the ability to specify "at least as fresh" as a Zookie.
153
153
154
-
SpiceDB simplifies this workflow by allowing API requests to specify their consistency behavior in addition to implementing ZedTokens, the analogue of Zanzibar's Zookies.
154
+
SpiceDB simplifies this workflow by allowing API requests to specify their consistency behavior in addition to implementing ZedTokens, the analogue of Zanzibar's Zookies. See [Consistency] for more details.
0 commit comments