GKaszewski/k-os
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(users): per-user sealed folders users/<id>/{home,apps,data,permissions}; storage SET_USER/LOCK/PURGE; init sign-in/sign-out loop (purge fresh/removed/guest, seed from factory, session start/stop); shell logout; pm user+system app shelves; terminal SIGNED_OUT; per-program stack (gatekeeper 12p); 128K load scratch

Browse Source
This commit is contained in:
Gabriel Kaszewski
2026-10-28 01:08:50 +01:00
parent 29a25bd8c2
commit 91f7d28834
38 changed files with 1156 additions and 378 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
docs/apps.md
View File

@@ -1,12 +1,12 @@
# Apps, manifests and the permission manager
How a program gets its authority. The kernel only knows capabilities; this
is the userspace layer that decides who holds which, on the owner's behalf
is the userspace layer that decides who holds which, on the user's behalf
(see the vision's Capability Management and App Manifest notes).
## Apps
Every program the owner runs is an **app**: a manifest plus a binary.
Every program a user runs is an **app**: a manifest plus a binary.
An app is identified by its **id** (`kos.snake`), never by a file name or a
process id. The id is what decisions, the app's data folder and (later) its
encryption keys hang off.
@@ -18,12 +18,12 @@ starts them from its own table, with exactly the capabilities listed there.
An app's capabilities have exactly two sources:
1. **Its manifest and the owner's consent.** Services the app declared
1. **Its manifest and the user's consent.** Services the app declared
(`display`, `storage`, …), granted only by the permission manager, only
as far as the owner approved.
as far as the user approved.
2. **Its launcher.** Whoever starts an app may pass along what it already
holds: the terminal as its output, a read-only grant to the current
folder, a file the owner picked. A launcher can only give what it has.
folder, a file the user picked. A launcher can only give what it has.
`cat` declares nothing and gets only what the shell passes it. Snake
declares `display`. Nothing gets anything "just in case".
@@ -31,22 +31,27 @@ declares `display`. Nothing gets anything "just in case".
## Disk layout
```
/home/ the owner's files; the shell's `/` (encrypted)
/apps/<id>/ an installed app: manifest.toml and its binary
/data/<id>/ the app's private folder (its `storage`) (encrypted, its own key)
/system/permissions/ the owner's decisions, one file per app id (encrypted)
/bin/ system servers and the shell (init starts these)
/factory/ plaintext starter content the encrypted areas are
seeded from with a new master key
/apps/<id>/ a system app: manifest.toml and its binary, shared by every user
/users/<user>/ one user's folder (encrypted, under their own key)
home/ their files; the shell's `/`
apps/<id>/ an app they installed
data/<id>/ an app's private folder (its `storage`, its own key)
permissions/<id> their decisions, one file per app id
/bin/ system servers and the shell (init starts these)
/factory/ plaintext starter content a user's folder is
seeded from (home/, permissions/, data/)
```
Only the permission manager reaches `/apps`, `/data` and `/system`. The
shell's storage grant is `/home`, so neither it nor anything it runs can
read another app's data or rewrite a decision.
Users each decide for themselves, even about the system's apps, and what
one installs the others do not see. An app id a system app has cannot be
installed. Only the signed-in user's folder opens. Only the permission
manager reaches their `apps/`, `data/` and `permissions/` (and `/apps`,
read-only). The shell's storage grant is their `home/`, so neither it nor
anything it runs can read an app's data or rewrite a decision.
## Manifest
`/apps/<id>/manifest.toml`, a strict subset of TOML:
`apps/<id>/manifest.toml`, a strict subset of TOML:
```toml
[app]
@@ -60,7 +65,7 @@ icon = "icon.png" # optional: a file in the app's folder
[capabilities]
required = ["display"] # cannot work without; denied = not installed
optional = [] # works without; the owner decides each
optional = [] # works without; the user decides each
[appearance]
accent = "#e91e63" # optional: checked for format here, contrast by K-UI
@@ -79,29 +84,29 @@ optional one is simply not granted.
| Capability | What the app gets |
|---|---|
| `display` | the display server: the screen, and the keyboard while in focus |
| `storage` | `/data/<id>/`, read-write (its own folder only) |
| `storage` | the user's `data/<id>/`, read-write (its own folder only) |
## Decisions
`/system/permissions/<id>`, the same TOML subset:
The user's `permissions/<id>`, the same TOML subset:
```toml
[decision]
granted = ["display"]
```
Written by the permission manager when the owner decides; apps on the
Written by the permission manager when the user decides; apps on the
system image ship with their decisions already recorded under
`factory/system/` (pre-approved by whoever built the image), and init
seeds them into the encrypted `system/` on a fresh setup. Changing one later is the owner's call, through
the permission manager.
`factory/permissions/` (pre-approved by whoever built the image), and init
seeds them into each new user's `permissions/`. Changing one later is that
user's call, through the permission manager.
## Permission manager
A system server with no hardware. Its logic (checking manifests, deciding
what an app gets, keeping decisions) is pure and generic over two ports:
- `Consent`: asks the owner. Today: a yes/no prompt on the terminal.
- `Consent`: asks the user. Today: a yes/no prompt on the terminal.
- `Store`: reads manifests and decisions, writes decisions, installs files.
Today: the storage server.
@@ -113,9 +118,9 @@ From a folder the launcher passes as a read-only grant:
1. Read and check its `manifest.toml`; refuse if the id is installed.
2. Required capabilities this device lacks: refuse.
3. Ask the owner about the required ones together (no = not installed),
3. Ask the user about the required ones together (no = not installed),
then each optional one.
4. Copy the binary and manifest to `/apps/<id>/`, create `/data/<id>/` if
4. Copy the binary and manifest to the user's `apps/<id>/`, create `data/<id>/` if
`storage` was granted, record the decision.
### Launch
@@ -136,7 +141,7 @@ permission manager:
### Revoke
The owner withdraws a capability: the decision changes and the next launch
The user withdraws a capability: the decision changes and the next launch
gets less. A running app that held it is **stopped**: all its access dies
at once. (Endpoint capabilities like `display` are copies the permission
manager cannot take back from one app alone yet; once servers issue