# 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 user's behalf (see the vision's Capability Management and App Manifest notes). ## Apps 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. System servers (log, display, terminal, storage, …) are not apps: init starts them from its own table, with exactly the capabilities listed there. ## Where authority comes from An app's capabilities have exactly two sources: 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 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 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". ## Disk layout ``` /apps// a system app: manifest.toml and its binary, shared by every user /users// one user's folder (encrypted, under their own key) home/ their files; the shell's `/` apps// an app they installed data// an app's private folder (its `storage`, its own key) permissions/ 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/) ``` 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//manifest.toml`, a strict subset of TOML: ```toml [app] id = "kos.snake" # required: lowercase reverse-DNS name = "Snake" # required version = "1.0.0" # required: major.minor.patch binary = "snake" # required: a file in the app's folder command = "snake" # optional: what the shell runs it as (default: binary) author = "K-OS" # optional icon = "icon.png" # optional: a file in the app's folder [capabilities] required = ["display"] # cannot work without; denied = not installed optional = [] # works without; the user decides each [appearance] accent = "#e91e63" # optional: checked for format here, contrast by K-UI ``` The subset: `[table]` headers, `key = "string"`, `key = ["a", "b"]` on one line, `#` comments. Strings hold printable ASCII without `"` or `\`. It is strict: an unknown table, key or capability name, a duplicate, or a missing required key rejects the manifest. Nothing is ignored silently. Capability names come from the server catalog (`display`, `storage`, `network`, `telephony`, …). A name is valid even if this device lacks the server; a required one it lacks means the app cannot be installed here, an optional one is simply not granted. | Capability | What the app gets | |---|---| | `display` | the display server: the screen, and the keyboard while in focus | | `storage` | the user's `data//`, read-write (its own folder only) | ## Decisions The user's `permissions/`, the same TOML subset: ```toml [decision] granted = ["display"] ``` Written by the permission manager when the user decides; apps on the system image ship with their decisions already recorded under `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 user. Today: a yes/no prompt on the terminal. - `Store`: reads manifests and decisions, writes decisions, installs files. Today: the storage server. Both have mocks; the logic is tested on the host with `cargo test`. ### Install 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 user about the required ones together (no = not installed), then each optional one. 4. Copy the binary and manifest to the user's `apps//`, create `data//` if `storage` was granted, record the decision. ### Launch The launcher names an app (by command or id), passes its arguments and the capabilities it wants to pass along (output, current folder). The permission manager: 1. Looks the app up and reads its decision. 2. Gives init a read-only grant to the binary; init loads it from that grant into a new, unstarted process (init needs no path, and nothing is spawned that its requester could not read). 3. Gives the process the granted services and what the launcher passed, writes its arguments page, starts it. 4. Watches it die, then releases its storage grants. 5. Replies with a handle (the process capability, call-only) the launcher can wait on and kill. ### Revoke 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 per-client badges, as storage does, revoking a single capability from a running app will not need to stop it.) ### Not yet - A trusted path for the consent prompt: today an app could draw a fake prompt on the terminal (it cannot answer one; apps cannot type). - Suspicious-combination warnings, simple/granular consent, per-host or other server-side scopes. - Signing, updates, uninstall.