Merge pull request #72 from polybase/eng-511-improve-permissions-docs

Improve permissions docs

Author: calummoore

_snippets/permissions/call-on-collections.mdx

@@ -0,0 +1,12 @@
+### `@call` on collections
+
+Allows anyone to call functions that do not have a `@call` directive.
+
+```js
+@call
+collection Form {
+  ...
+
+  updateTitle (title: string) { ... }
+}
+```

_snippets/permissions/call-on-functions.mdx

@@ -0,0 +1,15 @@
+### `@call` on functions
+
+Allows anyone who can sign using the specified public key to call a given function.
+
+```js
+collection Form {
+  @read
+  creator: PublicKey;
+
+  @call(creator);
+  update ()  {
+    ...
+  }
+}
+```

_snippets/permissions/delegate/delegate-call.mdx

@@ -0,0 +1,27 @@
+Example of delegating ***call permission*** to `Response` to a user with given `publicKey`:
+
+`Response` → `Form` → `User` → `publicKey`:
+
+```js
+collection Response {
+  form: Form;
+
+  // Delegate call permission to form/Form
+  @call(form)
+  function approve () {
+
+  }
+}
+
+collection Form {
+  // Delegate call permission to User
+  @delegate
+  creator: User;
+}
+
+collection User {
+  // Delegate call permission to publicKey
+  @delegate
+  publicKey: PublicKey;
+}
+```

_snippets/permissions/delegate/delegate-read.mdx

@@ -0,0 +1,23 @@
+Example of delegating ***read access*** to `Response` to a user with given `publicKey`:
+
+`Response` → `Form` → `User` → `publicKey`:
+
+```js
+collection Response {
+  // Delegate read permission to form/Form
+  @read
+  form: Form;
+}
+
+collection Form {
+  // Delegate read permission to User
+  @delegate
+  creator: User;
+}
+
+collection User {
+  // Delegate read permission to publicKey
+  @delegate
+  publicKey: PublicKey;
+}
+```

_snippets/permissions/delegate/desc.mdx

@@ -0,0 +1,8 @@
+Delegation allows you to create rules across multiple records, allowing for complex permissions to be defined.
+
+<Note>
+  Delegation rules must always end in a [PublicKey](/collections#public-key) field. You must
+   [authenticate the user with using a `signer`](/authentication) function in order to use delegation.
+</Note>
+
+You can annotate your collections with `@read`, `@call` and `@delegate` directives to control who can read, call and delegate data.

_snippets/permissions/public-on-collections.mdx

@@ -0,0 +1,11 @@
+### `@public` on collections
+
+Allows anyone to read all records and call functions in the collection (it's the equivalent of adding `@read` and `@call`). 
+You can still further restrict write permissions by adding custom code to your [collections functions](#functions).
+
+```js
+@public
+collection Response {
+  ...
+}
+```

_snippets/permissions/read-on-collections.mdx

@@ -0,0 +1,10 @@
+### `@read` on collections
+
+Allows anyone to read all records in the collection (but calls to functions are still restricted).
+
+```js
+@read
+collection Response {
+  ...
+}
+```

_snippets/permissions/read-on-fields.mdx

@@ -0,0 +1,11 @@
+### `@read` on fields
+
+Allows anyone who can sign using the specified public key to read the record.
+
+```js
+collection Response {
+  @read
+  publicKey: PublicKey;
+  ...
+}
+```

collections.mdx

@@ -551,101 +551,31 @@ collection cities {
 }
 ```
 
-## Authorization
+## Permissions
 
 By default, collections in Polybase are private and their records cannot be accessed.
-To make a collection private, remove the `@public` directive.
+To make a collection public, add the `@public` directive.
 
 To allow users to access and manipulate their records, you can use the following directives:
 
-### `@public` on collections
 
-Allows anyone to read records or call functions in the collection. You can still further
-restrict write permissions by adding custom code to your [collections functions](#functions).
+<Snippet file="permissions/public-on-collections.mdx" /> 
 
-```js
-@public
-collection Response {
-  ...
-}
-```
-
-### `@read` on collections
-
-Allows anyone to read records in the collection.
-
-```js
-@read
-collection Response {
-  ...
-}
-```
+<Snippet file="permissions/read-on-collections.mdx" /> 
 
-### `@read` on fields
+<Snippet file="permissions/read-on-fields.mdx" /> 
 
-Allows anyone who can sign using the specified public key to read the record.
+<Snippet file="permissions/call-on-collections.mdx" /> 
 
-```js
-collection Response {
-  @read
-  publicKey: PublicKey;
-  ...
-}
-```
-
-### `@call` on collections
-
-Allows anyone to call functions that do not have a `@call` directive.
-
-```js
-@call
-collection Form {
-  ...
-
-  updateTitle (title: string) { ... }
-}
-```
-
-### `@call` on functions
-
-Allows anyone who can sign using the specified public key to call a given function.
-
-```js
-collection Form {
-  @read
-  creator: PublicKey;
-
-  @call(creator);
-  update ()  {
-    ...
-  }
-}
-```
-
-A `@call` directive without arguments allows anyone to call the function.
+<Snippet file="permissions/call-on-functions.mdx" /> 
 
 ### `@delegate`
 
-Allows anyone who can sign using the specified public key to read the response data, via delegated permissions.
-
-Example of delegating `Response` → `Form` → `User` → `publicKey`:
-
-```js
-collection Response {
-  @read
-  form: Form;
-}
+<Snippet file="permissions/delegate/desc.mdx" /> 
 
-collection Form {
-  @delegate
-  creator: User;
-}
+<Snippet file="permissions/delegate/delegate-read.mdx" /> 
 
-collection User {
-  @delegate
-  publicKey: PublicKey;
-}
-```
+For more on delegating permissions, see [Delegating Permissions](/permissions#delegate).
 
 ## Reference a collection
 

encrypt-data.mdx

@@ -2,7 +2,7 @@
 title: "Encrypt data"
 ---
 
-Polybase data is publicly accessible, therefore sensitive data should be encrypted 
+Polybase can be publicly accessible (if [@public](permissions#public-on-collections) directive used). In the case of public data, sensitive data should be encrypted 
 before being written to the database. To make this process easier, Polybase has 
 created a helper library to handle common encryption tasks: 
 [`@polybase/util`](https://www.npmjs.com/package/@polybase/util)