doc: fix the-complete-guide space-user create rules (#415)

* doc: fix the-complete-guide space-user create rules * update

Author: ymc9

docs/reference/zmodel-language.md

@@ -1518,7 +1518,21 @@ A field can also contain an arbitrary number of policy rules. The logic of combi
 
 Please note the difference between model-level and field-level rules. Model-level access are by-default denied, while field-level access are by-default allowed.
 
-### Pre-update vs. post-update
+### "Create" rules
+
+The "create" policy rules should be understood as: **if an entity were to be created, would it satisfy the rules**. Or, in other words, the rules are checked "post create".
+
+An entity creating process works like the following:
+
+1. Initiate a transaction and create the entity.
+2. In the same transaction, try to read the created entity with the "create" rules as filter, and see if it succeeds.
+3. If the read fails, the transaction is rolled back; otherwise it's committed.
+
+The "post-create check" semantic allows the rules to access relations of the entity being created since they are only accessible after the create happens. For simple cases, ZenStack may apply optimizations to reject a create request without initiating a transaction, but generally speaking the "post-create check" semantic is the correct way to think about it.
+
+We may introduce a "pre-create" policy type in the future.
+
+### "Pre-update" vs." post-update" rules
 
 When an access policy rule is applied to a mutate operation, the entities under operation have a "pre" and "post" state. For a "create" rule, its "pre" state is empty, so the rule implicitly refers to the "post" state. For a "delete" rule, its "post" state is empty, so the rule implicitly refers to the "pre" state.
 

docs/the-complete-guide/part1/4-access-policy/4.4-relations.md

@@ -18,16 +18,16 @@ Accessing *-to-one relation is straightforward. You simply reference the field d
 
 ```zmodel
 model List {
-  id Int
-  private Boolean
+ id Int
+ private Boolean
 }
 
 model Todo {
-  id Int
-  list List @relation(...)
+ id Int
+ list List @relation(...)
 
-  // `list` references a to-one relation
-  @@allow('update', !list.private)
+ // `list` references a to-one relation
+ @@allow('update', !list.private)
 }
 ```
 
@@ -79,58 +79,64 @@ model Space {
 }
 
 model SpaceUser {
- ...
+ ...
+
+ // require login
+ @@deny('all', auth() == null)
 
- // require login
- @@deny('all', auth() == null)
+ // space owner can add any one
+ @@allow('create', space.owner == auth())
+ 
+ // space admin can add anyone but not himself
+ @@allow('create', auth() != user && space.members?[user == auth() && role == 'ADMIN'])
 
-  // space owner and admins have full access
-  @@allow('all', space.owner == auth() || space.members?[user == auth() && role == 'ADMIN'])
+ // space admin can update/delete
+ @@allow('update,delete', space.members?[user == auth() && role == 'ADMIN'])
 
-  // user can read members of spaces that he's a member of
-  @@allow('read', space.members?[user == auth()])
+ // user can read members of spaces that he's a member of
+ @@allow('read', space.members?[user == auth()])
 }
 
 model User {
-  ...
+ ...
 
-  // everyone can sign up
-  @@allow('create', true)
+ // everyone can sign up
+ @@allow('create', true)
 
-  // full access by oneself
-  @@allow('all', auth() == this)
+ // full access by oneself
+ @@allow('all', auth() == this)
 
-  // can be read by users sharing any space
-  @@allow('read', spaces?[space.members?[user == auth()]])
+ // can be read by users sharing any space
+ @@allow('read', spaces?[space.members?[user == auth()]])
 }
 
 model List {
-  ...
+ ...
 
-  // require login
-  @@deny('all', auth() == null)
+ // require login
+ @@deny('all', auth() == null)
 
-  // can be read by space members if not private
-  @@allow('read', owner == auth() || (space.members?[user == auth()] && !private))
+ // can be read by space members if not private
+ @@allow('read', owner == auth() || (space.members?[user == auth()] && !private))
 
-  // when create, owner must be set to current user, and user must be in the space
-  @@allow('create,update', owner == auth() && space.members?[user == auth()])
+ // when create, owner must be set to current user, and user must be in the space
+ @@allow('create,update', owner == auth() && space.members?[user == auth()])
 
-  // can be deleted by owner
-  @@allow('delete', owner == auth())
+ // can be deleted by owner
+ @@allow('delete', owner == auth())
 }
 
 model Todo {
-  ...
+ ...
 
-  // require login
-  @@deny('all', auth() == null)
+ // require login
+ @@deny('all', auth() == null)
 
-  // owner has full access
-  @@allow('all', list.owner == auth())
+ // owner has full access
+ @@allow('all', list.owner == auth())
 
-  // space members have full access if the parent List is not private
-  @@allow('all', list.space.members?[user == auth()] && !list.private)
+ // space members have full access if the parent List is not private
+ @@allow('all', list.space.members?[user == auth()] && !list.private)
 }
 ```
 
@@ -163,3 +169,37 @@ db.list.findMany()
 ```
 
 We queried with user Joey and now can get the `List` created by Rachel because Joey is a member of the same space.
+
+:::info A note about "create" rules
+
+You might have noticed we have two "create" rules in the `SpaceUser` model.
+
+```zmodel
+// space owner can add any one
+@@allow('create', space.owner == auth())
+
+// space admin can add anyone but not himself
+@@allow('create', auth() != user 
+ && space.members?[user == auth() && role == 'ADMIN'])
+```
+
+One might be tempting to use one simple rule like the following to allow space admins to create new memberships.
+
+```zmodel
+@@allow('create', space.members?[user == auth() && role == 'ADMIN'])
+```
+
+However, it'll be problematic due to "create" rule's semantic - **if an entity were to be created, would it satisfy the rules**? Or, in more details, a create process works like the following:
+
+1. Initiate a transaction and create the entity.
+2. In the same transaction, try to read the created entity with the "create" rules as filter, and see if it succeeds.
+3. If the read fails, the transaction is rolled back; otherwise it's committed.
+
+The "post-create check" semantic allows the rules to access relations of the entity being created. For simple cases, ZenStack may apply optimizations to reject a create request without initiating a transaction, but generally speaking the "post-create check" semantic is the correct way to think about it. We may introduce a "pre-create" policy type in the future.
+
+With these in mind, if we were to use the simple rule, a user can add himself to any space as "ADMIN", because after the create happens, the new membership would satisfy the rule. By splitting the rule into two, we can prevent this from happening:
+
+- Space owner can add anyone (including himself) into the space.
+- Space admin can add anyone but not himself.
+
+:::