From 82f86ee4ab7aecd2e25a970cde00226b3ce13d12 Mon Sep 17 00:00:00 2001 From: KernelDeimos Date: Thu, 20 Jun 2024 00:43:52 -0400 Subject: [PATCH] doc(backend): protected apps; function and permissions --- doc/docmeta.md | 12 ++++ packages/backend/doc/contributors/index.md | 36 +++++++++--- .../backend/doc/features/protected-apps.md | 29 ++++++++++ .../service-scripts.md | 0 .../lists-of-things/list-of-permissions.md | 55 +++++++++++++++++++ 5 files changed, 123 insertions(+), 9 deletions(-) create mode 100644 doc/docmeta.md create mode 100644 packages/backend/doc/features/protected-apps.md rename packages/backend/doc/{contributors => features}/service-scripts.md (100%) create mode 100644 packages/backend/doc/lists-of-things/list-of-permissions.md diff --git a/doc/docmeta.md b/doc/docmeta.md new file mode 100644 index 00000000..e693df33 --- /dev/null +++ b/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`) diff --git a/packages/backend/doc/contributors/index.md b/packages/backend/doc/contributors/index.md index c17fb0c3..52bebb8f 100644 --- a/packages/backend/doc/contributors/index.md +++ 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) -## Where to Start +## 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) + +## 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! diff --git a/packages/backend/doc/features/protected-apps.md b/packages/backend/doc/features/protected-apps.md new file mode 100644 index 00000000..4938cf54 --- /dev/null +++ b/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. diff --git a/packages/backend/doc/contributors/service-scripts.md b/packages/backend/doc/features/service-scripts.md similarity index 100% rename from packages/backend/doc/contributors/service-scripts.md rename to packages/backend/doc/features/service-scripts.md diff --git a/packages/backend/doc/lists-of-things/list-of-permissions.md b/packages/backend/doc/lists-of-things/list-of-permissions.md new file mode 100644 index 00000000..0e0efc30 --- /dev/null +++ b/packages/backend/doc/lists-of-things/list-of-permissions.md @@ -0,0 +1,55 @@ +# Permissions + +## Filesystem Permissions + +### `fs::` + +- `` 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. +- `` 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::`; + 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::access` +- `` 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#: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::access` + +- `` 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#: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.