1 files changed, 62 insertions, 0 deletions
diff --git a/permissions/table_permissions.md b/permissions/table_permissions.md
new file mode 100644
index 0000000..884744e
--- /dev/null
+++ b/permissions/table_permissions.md
@@ -0,0 +1,62 @@
+# Table Permissions
+
+[back to permissions](README.md) /// [home](../README.md)
+
+Every table has a permission code that controls what actions are allowed. These are set in the groups config (both core groups and toolkit groups). A compliant jsonderulo server must support all of these.
+
+## Permission Codes
+
+| Code | Name | Read | Write | Row Restriction |
+|------|------|------|-------|----------------|
+| `rwa` | read write all | yes | yes | none (can also write system columns) |
+| `rw` | read write | yes | yes | none |
+| `rwg` | read write group | yes | yes | only rows owned by users in your group |
+| `rwo` | read write own | yes | yes | only rows you own |
+| `r` | read | yes | no | none |
+| `rg` | read group | yes | no | only rows owned by users in your group |
+| `ro` | read own | yes | no | only rows you own |
+
+## What the codes mean
+
+### Full access codes
+
+**rwa** is the admin code. full read and write plus the ability to write system columns directly (like setting `pinned_to` to another user on insert). Only give this to trusted admin groups obviously.
+
+**rw** is standard read write. You can read and write everything but system columns should be auto managed by the server, you cant override them.
+
+### Scoped write codes
+
+**rwg** lets you read and write but only rows where `pinned_to` belongs to a user in the same core group as you. Good for team based access where a team can see and edit their own teams stuff.
+
+**rwo** same but personal. you can only touch rows where `pinned_to` equals your own user id.
+
+### Read only codes
+
+**r** read everything, write nothing.
+
+**rg** read only rows belonging to your groups users.
+
+**ro** read only your own rows.
+
+## Format in config
+
+Permission rules are stored as JSON arrays of `"table:code"` strings:
+
+```json
+["*:rw", "jde_settings:r", "vfy_logs:r"]
+```
+
+`*` is the wildcard. It applies to every table that doesnt have its own explicit rule. So in the example above every table gets `rw` except `jde_settings` and `vfy_logs` which are read only.
+
+## Read only tables
+
+Tables marked as `read_only` in the toolkit config should automatically have their writable codes downgraded:
+
+| Original | Downgraded to |
+|----------|--------------|
+| `rwa` | `r` |
+| `rw` | `r` |
+| `rwg` | `rg` |
+| `rwo` | `ro` |
+
+So even if your group gives you `rw` on a read only table you effectively only get `r`.