doc(backend): protected apps; function and permissions

doc/docmeta.md

@@ -0,0 +1,12 @@
+# Meta Documentation
+
+## Notes
+
+- > This  document is a work-in-progress
+
+## Rules
+
+### "is" and "is not"
+
+- When "A is B", always bold "is": "A **is** B" (`A **is** B`)
+- When "A is not B", always bold "not": "A is **not** B" (`A is **not** B`)

packages/backend/doc/contributors/index.md

@@ -1,16 +1,24 @@
 # Contributing to Puter's Backend
 
-## Initial Reading
+## Architecture
 
-- [puter-js-common's README.md](../../packages/puter-js-common/README.md)
-  - Whenever you see `AdvancedBase`, that's from here
-    - Many things in backend extend this. Anything that doesn't only doesn't
-      because it was written before `AdvancedBase` existed.
-  - Allows adding "traits" to classes
-    - Have you ever wanted to wrap every method of a class with
-      common behavior? This can do that!
+- [boot sequence](./boot-sequence.md)
+- [modules and services](./modules.md)
+
+## Features
+
+- [protected apps](../features/protected-apps.md)
+- [service scripts](../features/service-scripts.md)
+
+## Lists of Things
+
+- [list of permissions](../lists-of-things/list-of-permissions.md)
 
-## Where to Start
+## Code-First Approach
+
+If you prefer to understand a system by looking at the
+first files which are invoked and starting from there,
+here's a handy list!
 
 - [Kernel](../../src/Kernel.js), despite its intimidating name, is a
   relatively simple (< 200 LOC) class which loads the modules
@@ -60,3 +68,13 @@ There's no easy solution for this so just keep it in mind; there are some
 things we might write 2 times, 3 times, even more times over before we
 really get it right and *that's okay*; sometimes part of doing useful work is
 doing the useless work that reveals what the useful work is.
+
+## Underlying Constructs
+
+- [puter-js-common's README.md](../../packages/puter-js-common/README.md)
+  - Whenever you see `AdvancedBase`, that's from here
+    - Many things in backend extend this. Anything that doesn't only doesn't
+      because it was written before `AdvancedBase` existed.
+  - Allows adding "traits" to classes
+    - Have you ever wanted to wrap every method of a class with
+      common behavior? This can do that!

packages/backend/doc/features/protected-apps.md

@@ -0,0 +1,29 @@
+# Protected Apps and Subdomains
+
+## Protected Sites
+
+If a site is not protected, anyone can access the site.
+When a site is protected, the following changes:
+
+- The site can only be accessed inside a Puter app iframe
+- Only users with explicit permission will be able to load
+  the page associated with the site.
+
+## Protected Apps
+
+If an app is not protected, anyone with the name of the
+app or its UUID will be able to access the app.
+If the app is **approved for listing** (todo: doc this)
+all users can access the app.
+If an app is protected, the following changes:
+
+- The app can only be "seen" (listed) by users
+  with explicit permission.
+- App metadata can only be accessed by users
+  with explicit permission.
+
+Note that an app being protected does not imply that the
+site is protected. If a user action results in an app
+being protected it should also result in the site (subdomain)
+being protected **if they own it**. If the site will not
+be protected the user should have some indication.

packages/backend/doc/lists-of-things/list-of-permissions.md

@@ -0,0 +1,55 @@
+# Permissions
+
+## Filesystem Permissions
+
+### `fs:<PATH-OR-UUID>:<ACCESS-LEVEL>`
+
+- `<PATH-OR-UUID>` specifies the file that this permission
+  is associated with.
+  The ACL service
+  (which checks filesystem permissions)
+  knows if the value is a path or UUID based on the presence
+  of a leading slash; if it starts with `"/"` it's a path.
+- `<ACCESS-LEVEL>` specifies one of:
+  `write`, `read`, `list`, `see`; where each item in that
+  list implies all the access levels which follow.
+- A permission that grants access to a directory,
+  such as `/user/shared`, implies access
+  of the same **access level** to all child file or directory
+  nodes under that location, **recursively**;
+  `fs:/user/shared:read` implies `fs:/user/shared/nested/file.txt:read`
+- The "real" permission is `fs:<UUID>:<ACCESS-LEVEL>`;
+  whenever path is specified the permission is rewritten.
+  **note:** future support for other filesystems
+  could make this rewrite rule conditional.
+
+## App and Subdomain permissions
+
+### `site:<NAME-OF-SITE>:access`
+- `<NAME-OF-SITE>` specifies the subdomain that this
+  permission is associated with.
+  Here, "subdomain" means the **"name of the subdomain"**,
+  which means a site accessed via `my-name.example.site`
+  will be specified here with `my-name`.
+- This permission is always rewritten as the permission
+  described below (backend does this automatically).
+
+### `site:uid#<UUID-OF-SITE>:access`
+- If the subdomain is **not** [protected](../features/protected-apps.md),
+  this permission is ignored by the system.
+- If the subdomain **is** protected, this permission will
+  allow access to the site via a Puter app iframe with
+  a token for the entity to which permission was granted
+
+### `app:<NAME-OF-APP>:access`
+
+- `<NAME-OF-APP>` specifies the app that this
+  permission is associated with.
+- This permission is always rewritten as the permission
+  described below (backend does this automatically).
+  
+### `app:uid#<UUID-OF-APP>:access`
+- If the app is **not** [protected](../features/protected-apps.md),
+  this permission is ignored by the system.
+- If the app **is** protected, this permission will
+  allow reading the app's metadata and seeing that the app exists.