1 files changed, 68 insertions, 0 deletions
diff --git a/toolkits/permissions.md b/toolkits/permissions.md
new file mode 100644
index 0000000..e32e9d3
--- /dev/null
+++ b/toolkits/permissions.md
@@ -0,0 +1,68 @@
+# Toolkit Permissions
+
+[back to toolkits](README.md) /// [home](../README.md)
+
+How toolkit specific permissions work and how they get merged with core permissions.
+
+## Toolkit groups
+
+Each toolkit can have its own groups table (configured via `groups_table`). This table needs at minimum:
+
+| Column                 | Type    | Notes                                                                     |
+|------------------------|---------|---------------------------------------------------------------------------|
+| `name`                 | VARCHAR | group name, referenced by `jde_associations.toolkit_group_name`           |
+| `permissions`          | JSON    | array of permission rules (same format as core: `["table:rw", "logs:r"]`) |
+| `endpoint_permissions` | JSON    | array of allowed endpoint paths like this `["kiosk/*", "report"]`         |
+
+## Associations
+
+Core groups are linked to toolkit groups via the `jde_associations` junction table. One entry per core group per toolkit:
+
+```
+core group "staff" (power 50) -> beepzone toolkit -> beepzone group "operators"
+core group "admin" (power 100) -> beepzone toolkit -> beepzone group "managers"
+```
+
+When a user authenticates the server knows their core group which gives their power level and core permissions. Then for each toolkit it looks up the association to find their toolkit group and merges those permissions in.
+
+## Permission resolution
+
+At startup and on config reload the server should:
+
+1. read core groups from `jde_groups`
+2. read toolkit groups from each toolkits `groups_table`
+3. join them through `jde_associations`
+4. merge the permission rules per power level
+5. build the reals jsonderulo RBAC structure
+
+Toolkit permissions are additive to core permissions. If core gives you `r` on a table and the toolkit gives you `rw` on the same table you end up with `rw`.
+
+## User level overrides
+
+Users can have `toolkit_overrides` in their JSON preferences on `jde_users`:
+
+```json
+[{ "toolkit": "beepzone", "group": "manager" }]
+```
+
+This overrides the association from their core group. So even if their core group maps to "operators" in beepzone they personally get "manager" permissions.
+
+## Fallback permissions
+
+When the database is partially fucked or the groups table doesnt exist yet the server can fall back to static permissions defined in the toolkit config and users table, they should look somewhat the same as 
+
+```toml
+[db_fallback_permissions.100]
+basic_rules = ["assets:rw", "logs:r"]
+advanced_rules = ["assets.secret_field:block"]
+```
+
+The key is the power level as a string. These only kick in when DB sourced permissions arent really available (or if the server implementation allows setting preferences as to which one wins if both are set)
+
+## Endpoint permissions
+
+Separate from table permissions. Endpoint permissions control which custom endpoint paths a user can access. These are resolved per power level from the toolkit groups `endpoint_permissions` column.
+
+Glob patterns are supported: `"kiosk/*"` matches all paths under kiosk.
+
+Endpoint fallback permissions can also be defined in the toolkit config for when the database isnt available.