🗯️ Let's talk about Appwrite's permissions once more

[Meldiron]

👋 hello("World")

There are some limitations to the current permission system, and we would love to address them in future releases. Some of these problems can be solved by separating data into multiple collections (to have multiple permission control points), and some needs to be solved with the Appwrite Function (custom backend). With that said, we can all agree that both of these solutions can be annoying, and everyone would benefit from a more robust permission solution.

🧰 Permission Levels Refactor

🔥 As of right now, you either apply document-level or collection-level permissions. You can never apply both, which makes some use cases difficult (unless you write Appwrite Function for it). We did this because previously, we applied both permission levels at the same time, but developers found that hard to understand.

🧯 We came up with a solution to go back to using both while still keeping it dead simple to understand. Long story short:

During the permissions check, both collection and document permissions are checked. This means you only need permission at one of the levels to have access.

Here is an example use case: Almost Reddit. There are Reddit admins that can delete any subreddit. If you create a subreddit, you can change its description but not delete it. Such an app would look like this:

Collection-level permissions: read("any"), write("team:admins")
Document-level permissions (enabled): update("user:Meldiron")

🎛️ Getting Specific with update and delete

🔥 As of right now, we have write permission that allows you both update and delete resources.

🧯 Solution? Simple! We are going to introduce separate update and delete permissions so you can get specific if necessary for your project. No need to worry, write will stay as an alias and will couple create, update and delete for collections/buckets, and update and delete for documents/files

📰 Brand-New create Permission

🔥 As of right now, it’s really unclear who can create documents. With collection level, it’s whoever has write permission. This can be a problem because if you give someone this collection-level write permission, they can also edit all documents in the collection and delete them. With document-level permission, you have no control over who can create a document since it’s allowed to all signed-in users.

🧯 We solve this problem by introducing create permission, which is only there on collection and bucket (not on document or file). We also decided to support role:all for all create actions, in order to allow unauthorized visitors to createDocument createFile, createExecution.

⚡ Permissions, Meet Queries 2.0!

We recently started a discussion on improving our current querying system. You can read more about it here: #3545 . The new query system got positive feedback, so we decided to introduce it to our permissions too. Introducing... 🥁🥁🥁 Permission queries!

🔥 As of right now, you had to pass a separate array of string permissions for both read and write. This can be inconvenient sometimes since string values are prone to typos, and on top of that, you would now be forced to have 2 more arrays for update and delete introduced earlier in this discussion.

🧯 Query syntax comes to the rescue and removes all of these array parameters. They get replaced by one array parameter, permissions, and in there, you can specify All the permissions you want to set.

Here is what a code snippet might have looked like if we didn't introduce permission queries:

database.createDocument(
  "articles", // collectionID
  "unique()", // documentID
  data, // Document itself
  [ 'role:all' ], // read permissions
  [ 'team:moderators', 'team:admins', 'user:Meldiron' ], // update permissions
  [ 'team:moderators', 'team:admins' ], // delete permissions
);

You might get lost in the order of params, as well as no possibility for aliases (like write). Here is the same snippet, but this time with permission queries:

database.createDocument(
  ID.custom("articles"), // collectionID
  ID.unique(), // documentID
  data, // Document itself
  [ // permissions
    Permission.read(Role.any()),
    Permission.delete(Role.guests()),
    Permission.read(Role.team('moderators')),
    Permission.read(Role.team('admins')),
    Permission.read(Role.team('admins', 'owner')),
    Permission.delete(Role.user('meldiron')),
  ]
);

📚 Simpler naming convention

🔥 As of right now, we have permissions like role:member to determine the user's authentication status. If you are familiar with all Appwrite services, you might have noticed that both words role and membership are used with TeamsAPI, not Account/User APIs. The naming convention we have right now is not too clear and is not consistent with the rest of Appwrite.

🧯 Let's make it simple!

Before	After
role:all	any
role:member	users
role:guest	guests

Possibilities are still the same, it's just easier to understand and remember.

[s3ppo]

I like it but i see a lot of braking changes coming 🙈

[eldadfux]

Trying to squeeze every last breaking change before 1.0 🙏

[eldadfux]

We also consider to keep support for old role names for at least a few more months.

[eldadfux]

Love the new SDK experience. We might be able to provide auto-completion to roles as well.

[reyesmfabian]

One question, in previous discussions about permissions we indicated the need to be able to establish permissions to other users or teams without having to belong to them to avoid the use of Cloud Functions as was done in versions below 0.12. Is this being reviewed? Or should we definitely use cloud functions or the server SDK for these cases?

[eldadfux]

The recommendation is still to use Functions for this use case. We decided not to couple this topic as part of this scope as it’s much more complex and wide. That said, permission sharing API / capabilities are still something we want to look into

[PavieOlivier]

One question, Previously, on Discord, @eldadfux mentioned that you guys will be looking at adding "Custom Roles".
Is this still on your plans? I can definitely see myself using permission queries like this (even though I do not feel it is that necessary anymore ):

database.createDocument(
  ID.custom("articles"), // collectionID
  ID.unique(), // documentID
  data, // Document itself
  [ // permission
    Permission.read(Role.custom('moderator')),
  ]
);

[eldadfux]

Yeh, I'm still advocating for something like user labels that could only be set from server side or the console and allow a new role like label:vip.

[BenMemescape]

The Permission and Role helper classes are fine for creating new permissions from scratch, but they currently lack any way of parsing permissions retrieved from an existing collection or document.

Suppose there's a doc that has permissions for team:12345 to read and update. If I want to create another doc which copies the read permission from the first doc, but not the update permission, I seem to have no choice but to parse the permissions strings myself, looking for one that matches /^read\(/, and copy it directly as a string, which somewhat undermines the point of having helper classes to hide the implementation detail of those strings...

Previously this was easy, because read and write were separate parameters to createDocument, so I could just reflect back the read parameter. The new unified permissions are a step backwards in this regard.