daniel/MontaukOS
1
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: implement kernel capability model

Browse Source
This commit is contained in:
daniel
2026-08-29 16:53:04 +02:00
parent 9051b8a16e
commit e7646bbbdb
47 changed files with 1507 additions and 264 deletions
Download Patch File Download Diff File Expand all files Collapse all files
programs/include/Api/Syscall.hpp
+67
View File
@@ -250,6 +250,63 @@ namespace montauk::abi {
static constexpr uint64_t SYS_LOG_WRITE = 176; // (logMessage) -> 0
static constexpr uint64_t SYS_TERMINAL_ATTACHED = 177; // () -> 1 when connected to a userspace terminal
static constexpr uint64_t SYS_SPAWN_CAPS = 185;
static constexpr uint64_t SYS_SPAWN_REDIR_CAPS = 186;
/* Kernel-owned process capabilities. User identities may namespace
per-user resources, but never participate in authorization decisions. */
static constexpr uint64_t CAP_PROCESS_ADMIN = 1ULL << 0;
static constexpr uint64_t CAP_POWER_REQUEST = 1ULL << 1;
static constexpr uint64_t CAP_POWER_CONTROL = 1ULL << 2;
static constexpr uint64_t CAP_SUSPEND = 1ULL << 3;
static constexpr uint64_t CAP_STORAGE_ADMIN = 1ULL << 4;
static constexpr uint64_t CAP_RAW_STORAGE = 1ULL << 5;
static constexpr uint64_t CAP_NETWORK_ADMIN = 1ULL << 6;
static constexpr uint64_t CAP_SET_TIME = 1ULL << 7;
static constexpr uint64_t CAP_USER_ADMIN = 1ULL << 8;
static constexpr uint64_t CAP_DISPLAY_ADMIN = 1ULL << 9;
static constexpr uint64_t CAP_DEVICE_ADMIN = 1ULL << 10;
static constexpr uint64_t CAP_LOG_READ = 1ULL << 11;
/* Write to the program images the system boots and runs (0:/os,
0:/apps). Deliberately separate from CAP_STORAGE_ADMIN: grants are
keyed on binary path, so writing an image is equivalent to acquiring
whatever that image is granted at its next launch. Formatting a data
volume must not carry that authority with it. */
static constexpr uint64_t CAP_SYSTEM_IMAGE = 1ULL << 12;
static constexpr uint64_t CAP_ALL = (1ULL << 13) - 1;
static constexpr uint64_t CAP_STANDARD_SESSION = CAP_POWER_REQUEST | CAP_SUSPEND;
static constexpr uint64_t CAP_ADMIN_SESSION =
CAP_STANDARD_SESSION | CAP_PROCESS_ADMIN | CAP_STORAGE_ADMIN |
CAP_RAW_STORAGE | CAP_NETWORK_ADMIN | CAP_SET_TIME | CAP_USER_ADMIN |
CAP_DISPLAY_ADMIN | CAP_DEVICE_ADMIN | CAP_LOG_READ;
static_assert((CAP_STANDARD_SESSION & ~CAP_ADMIN_SESSION) == 0);
static_assert((CAP_ADMIN_SESSION & CAP_POWER_CONTROL) == 0,
"final power control belongs only to the session supervisor");
static_assert((CAP_ADMIN_SESSION & CAP_SYSTEM_IMAGE) == 0,
"an admin session must not imply authority to rewrite the "
"programs it launches; grant CAP_SYSTEM_IMAGE per binary");
static constexpr int SYS_ERR_PERMISSION = -13;
struct SpawnCapabilities {
uint64_t permitted;
uint64_t effective;
uint64_t delegable;
};
constexpr bool ValidCapabilityDelegation(const SpawnCapabilities& child,
uint64_t parentDelegable) {
return (child.permitted & ~CAP_ALL) == 0 &&
(child.effective & ~child.permitted) == 0 &&
(child.delegable & ~child.permitted) == 0 &&
(child.permitted & ~parentDelegable) == 0 &&
(child.delegable & ~parentDelegable) == 0;
}
static_assert(ValidCapabilityDelegation(
{CAP_NETWORK_ADMIN, CAP_NETWORK_ADMIN, 0}, CAP_NETWORK_ADMIN));
static_assert(!ValidCapabilityDelegation(
{CAP_NETWORK_ADMIN, CAP_NETWORK_ADMIN, CAP_NETWORK_ADMIN}, 0));
static_assert(!ValidCapabilityDelegation(
{CAP_NETWORK_ADMIN, CAP_NETWORK_ADMIN | CAP_SET_TIME, 0}, CAP_ALL));
static constexpr int USB_ERR_INVALID = -1;
@@ -264,10 +321,17 @@ namespace montauk::abi {
// Graceful power-off request actions (SYS_POWER_REQUEST). The desktop posts
// a pending action and exits; login.elf reads it, runs the shutdown stages,
// then issues the matching SYS_SHUTDOWN / SYS_RESET.
//
// A request can also be posted from inside the session -- the shell's
// shutdown builtin does. login only looks at it once the session leader
// exits, so the leader has to notice and stand down: POWER_REQ_PEEK is the
// non-destructive read it polls with. Only login consumes (QUERY), so a
// leader that peeks cannot swallow the request it is meant to act on.
enum PowerRequestAction : int {
POWER_REQ_QUERY = 0, // read-and-clear the pending action
POWER_REQ_SHUTDOWN = 1,
POWER_REQ_REBOOT = 2,
POWER_REQ_PEEK = 3, // read the pending action without clearing it
};
static constexpr uint32_t CLIPBOARD_MAX_TEXT_BYTES = 256 * 1024;
@@ -729,6 +793,9 @@ namespace montauk::abi {
char name[64];
uint64_t heapUsed; // Distance from UserHeapBase to high-water mark
uint64_t cpuTimeMs; // accumulated scheduler runtime
uint64_t permittedCaps;
uint64_t effectiveCaps;
uint64_t delegableCaps;
};
struct MemStats {
programs/include/gui/terminal.hpp
+14 -1
View File
@@ -10,6 +10,7 @@
#include <montauk/syscall.h>
#include <montauk/string.h>
#include <Api/Syscall.hpp>
#include <montauk/capabilities.h>
namespace gui {
@@ -212,7 +213,19 @@ static inline void terminal_init(TerminalState* t, int cols, int rows) {
terminal_init_cells(t, cols, rows, TERM_MAX_SCROLLBACK);
t->cursor_visible = true;
t->child_pid = montauk::spawn_redir("0:/os/shell.elf");
// A console shell is a session launcher, exactly like the desktop, and is
// granted on exactly the same terms: 0:/config/capabilities.toml decides
// what shell.elf receives, and the kernel clamps that to what this session
// was actually delegated. Deriving the grant here instead would be a
// second, hardcoded list of "capabilities a console may confer" -- one the
// table cannot see and cannot keep in step with.
static constexpr const char* kShellPath = "0:/os/shell.elf";
montauk::abi::SpawnCapabilities caps =
montauk::caps::for_binary(kShellPath, montauk::caps::self_delegable());
t->child_pid = (caps.permitted != 0)
? montauk::spawn_redir_with_caps(kShellPath, nullptr, caps)
: montauk::spawn_redir(kShellPath);
if (t->child_pid > 0)
montauk::childio_settermsz(t->child_pid, cols, rows);
}
programs/include/libc/montauk.h
+8 -6
View File
@@ -208,6 +208,8 @@ extern "C" {
#define MTK_SYS_USB_BULK_IN_START 182
#define MTK_SYS_USB_BULK_IN_STOP 183
#define MTK_SYS_USB_BULK_IN_READ 184
#define MTK_SYS_SPAWN_CAPS 185
#define MTK_SYS_SPAWN_REDIR_CAPS 186
/* @SYSCALLS-END */
#define MTK_SOCK_TCP 1
@@ -683,8 +685,8 @@ static inline int mtk_set_unix_time(int64_t unix_seconds) {
return (int)_mtk_syscall1(MTK_SYS_SETUNIXTIME, (long)unix_seconds);
}
static inline void mtk_settz(int offset_minutes) {
_mtk_syscall1(MTK_SYS_SETTZ, (long)offset_minutes);
static inline int mtk_settz(int offset_minutes) {
return (int)_mtk_syscall1(MTK_SYS_SETTZ, (long)offset_minutes);
}
static inline int mtk_gettz(void) {
@@ -883,12 +885,12 @@ static inline int mtk_audio_ctl(int handle, int cmd, int value) {
Power management
==================================================================== */
static inline void mtk_reset(void) {
_mtk_syscall0(MTK_SYS_RESET);
static inline int mtk_reset(void) {
return (int)_mtk_syscall0(MTK_SYS_RESET);
}
static inline void mtk_shutdown(void) {
_mtk_syscall0(MTK_SYS_SHUTDOWN);
static inline int mtk_shutdown(void) {
return (int)_mtk_syscall0(MTK_SYS_SHUTDOWN);
}
/* ====================================================================
programs/include/montauk/capabilities.h
+216
View File
@@ -0,0 +1,216 @@
/*
* capabilities.h
* Shared reader for the capability grant table (0:/config/capabilities.toml)
* Copyright (c) 2026 Daniel Hammer
*/
#pragma once
#include <montauk/syscall.h>
#include <montauk/toml.h>
#include <montauk/config.h>
#include <montauk/heap.h>
/*
* Launchers (init, the desktop, the shell) look up the authority a program
* should receive here instead of each carrying its own compiled-in table.
*
* This file is advisory, never authoritative. Every grant still goes
* through SYS_SPAWN_CAPS and is validated in the kernel against the
* caller's own delegable set, so nothing written here can produce authority
* the kernel has not already delegated to the launcher. A missing,
* truncated or hostile file can only ever result in a program receiving
* less authority than intended. That is why the table can live in
* userspace TOML: the kernel enumerates protected paths, userspace
* interprets policy.
*
* Grants are keyed on the resolved binary path, which is what makes the
* table safe to hand to init: pointing a privileged service entry at a
* different executable looks up the new path, finds no entry, and grants
* nothing. The kernel write-protects 0:/apps and 0:/os so the path cannot
* be made to refer to a substituted image.
*/
namespace montauk {
namespace caps {
inline constexpr const char* GRANT_CONFIG = "capabilities";
inline constexpr const char* GRANT_PREFIX = "grant.";
inline constexpr int MAX_SCAN_PROCS = 256;
struct CapName {
const char* name;
uint64_t bit;
};
// Names as they appear in the config file. Kept in the same order as the
// CAP_* bit definitions in Api/Syscall.hpp.
inline constexpr CapName NAMES[] = {
{"process_admin", montauk::abi::CAP_PROCESS_ADMIN},
{"power_request", montauk::abi::CAP_POWER_REQUEST},
{"power_control", montauk::abi::CAP_POWER_CONTROL},
{"suspend", montauk::abi::CAP_SUSPEND},
{"storage_admin", montauk::abi::CAP_STORAGE_ADMIN},
{"raw_storage", montauk::abi::CAP_RAW_STORAGE},
{"network_admin", montauk::abi::CAP_NETWORK_ADMIN},
{"set_time", montauk::abi::CAP_SET_TIME},
{"user_admin", montauk::abi::CAP_USER_ADMIN},
{"display_admin", montauk::abi::CAP_DISPLAY_ADMIN},
{"device_admin", montauk::abi::CAP_DEVICE_ADMIN},
{"log_read", montauk::abi::CAP_LOG_READ},
{"system_image", montauk::abi::CAP_SYSTEM_IMAGE},
};
inline uint64_t bit_for_name(const char* name) {
if (name == nullptr || name[0] == '\0') return 0;
// "all" means "everything this launcher may pass on", which the
// caller-delegable clamp in for_binary() then narrows. It excludes
// CAP_SYSTEM_IMAGE: authority to rewrite a program image is never
// something a wildcard should hand out, only an explicit name.
if (montauk::streq(name, "all"))
return montauk::abi::CAP_ALL & ~montauk::abi::CAP_SYSTEM_IMAGE;
for (const auto& entry : NAMES) {
if (montauk::streq(entry.name, name)) return entry.bit;
}
// Unknown names are ignored rather than rejected. Failing closed
// costs a program some authority; failing open would hand out
// authority nobody asked for.
return 0;
}
// Read an array-of-strings key into a capability mask. A missing key is
// an empty mask, which is the correct default for an absent grant.
inline uint64_t mask_from_key(const montauk::toml::Doc& doc, const char* key) {
montauk::toml::Value* arr = doc.get_array(key);
if (arr == nullptr) return 0;
uint64_t mask = 0;
for (int i = 0; i < arr->array.count; i++) {
montauk::toml::Value* item = arr->array.items[i];
if (item == nullptr || item->type != montauk::toml::Type::String) continue;
mask |= bit_for_name(item->str);
}
return mask;
}
// Append `suffix` to the "grant.<id>." stem of `path_key`.
// Returns false if the key is not of that shape or does not fit.
inline bool build_sibling_key(const char* path_key, const char* suffix,
char* out, int outSz) {
int prefixLen = 0;
for (; GRANT_PREFIX[prefixLen]; prefixLen++) {
if (path_key[prefixLen] != GRANT_PREFIX[prefixLen]) return false;
}
// Copy through the final '.' so "grant.foo.path" yields "grant.foo.".
int lastDot = -1;
for (int i = 0; path_key[i]; i++) {
if (path_key[i] == '.') lastDot = i;
}
if (lastDot < prefixLen) return false;
int n = 0;
for (; n <= lastDot && n < outSz - 1; n++) out[n] = path_key[n];
for (int i = 0; suffix[i] && n < outSz - 1; i++) out[n++] = suffix[i];
out[n] = '\0';
return true;
}
// Look up the grant declared for `binary_path`. Returns false when the
// path has no entry, which is the common case and means "no authority".
inline bool lookup(const char* binary_path,
montauk::abi::SpawnCapabilities& out) {
out = {0, 0, 0};
if (binary_path == nullptr || binary_path[0] == '\0') return false;
montauk::toml::Doc doc = montauk::config::load(GRANT_CONFIG);
bool found = false;
for (int i = 0; i < doc.entries.count && !found; i++) {
montauk::toml::Value* entry = doc.entries.items[i];
if (entry == nullptr || entry->key == nullptr) continue;
if (entry->type != montauk::toml::Type::String) continue;
char sibling[128];
if (!build_sibling_key(entry->key, "path", sibling, sizeof(sibling))) continue;
if (!montauk::streq(sibling, entry->key)) continue;
if (!montauk::streq(entry->str, binary_path)) continue;
build_sibling_key(entry->key, "effective", sibling, sizeof(sibling));
uint64_t effective = mask_from_key(doc, sibling);
build_sibling_key(entry->key, "delegable", sibling, sizeof(sibling));
uint64_t delegable = mask_from_key(doc, sibling);
build_sibling_key(entry->key, "permitted", sibling, sizeof(sibling));
uint64_t permitted = mask_from_key(doc, sibling);
// A grant that does not name `permitted` owns exactly what it can
// use or pass on. Declaring it separately is only needed by a
// supervisor that holds authority in reserve (login).
if (permitted == 0) permitted = effective | delegable;
out.permitted = permitted;
out.effective = effective;
out.delegable = delegable;
found = true;
}
doc.destroy();
return found;
}
// The calling process's own capability masks.
//
// There is no syscall to ask "what am I?", so this scans the process table
// for our own PID. The buffer is heap-allocated because ProcInfo is large
// enough that MAX_SCAN_PROCS of them would be a ~29 KB stack frame.
inline bool self(montauk::abi::SpawnCapabilities& out) {
out = {0, 0, 0};
auto* table = (montauk::abi::ProcInfo*)montauk::malloc(
sizeof(montauk::abi::ProcInfo) * MAX_SCAN_PROCS);
if (table == nullptr) return false;
int count = montauk::proclist(table, MAX_SCAN_PROCS);
int self_pid = montauk::getpid();
bool found = false;
for (int i = 0; i < count; i++) {
if (table[i].pid != self_pid) continue;
out.permitted = table[i].permittedCaps;
out.effective = table[i].effectiveCaps;
out.delegable = table[i].delegableCaps;
found = true;
break;
}
montauk::mfree(table);
return found;
}
inline uint64_t self_delegable() {
montauk::abi::SpawnCapabilities mine;
return self(mine) ? mine.delegable : 0;
}
// Build a spawn request for `binary_path`, clamped to what the caller may
// actually delegate. The kernel enforces the same bound; clamping here
// means a launcher that holds less authority than the table declares
// degrades to a reduced grant instead of failing the spawn outright.
inline montauk::abi::SpawnCapabilities for_binary(const char* binary_path,
uint64_t caller_delegable) {
montauk::abi::SpawnCapabilities caps{0, 0, 0};
// A caller with nothing to delegate cannot produce a non-empty grant,
// so skip the file read entirely. This is the common case: every
// unprivileged session, on every launch.
if (caller_delegable == 0) return caps;
if (!lookup(binary_path, caps)) return caps;
caps.permitted &= caller_delegable;
caps.effective &= caps.permitted;
caps.delegable &= caps.permitted;
return caps;
}
} // namespace caps
} // namespace montauk
programs/include/montauk/syscall.h
+29 -7
View File
@@ -120,6 +120,13 @@ namespace montauk {
inline int spawn(const char* path, const char* args = nullptr) {
return (int)syscall2(montauk::abi::SYS_SPAWN, (uint64_t)path, (uint64_t)args);
}
inline int spawn_with_caps(const char* path, const char* args,
const char* user,
const montauk::abi::SpawnCapabilities& capabilities) {
return (int)syscall4(montauk::abi::SYS_SPAWN_CAPS, (uint64_t)path,
(uint64_t)args, (uint64_t)user,
(uint64_t)&capabilities);
}
inline int chdir(const char* path) {
return (int)syscall1(montauk::abi::SYS_CHDIR, (uint64_t)path);
}
@@ -391,7 +398,10 @@ namespace montauk {
}
// Timezone offset (total minutes from UTC)
inline void settz(int offset_minutes) { syscall1(montauk::abi::SYS_SETTZ, (uint64_t)(int64_t)offset_minutes); }
inline int settz(int offset_minutes) {
return (int)syscall1(montauk::abi::SYS_SETTZ,
(uint64_t)(int64_t)offset_minutes);
}
inline int gettz() { return (int)syscall0(montauk::abi::SYS_GETTZ); }
// Random number generation
@@ -400,14 +410,12 @@ namespace montauk {
}
// Power management
[[noreturn]] inline void reset() {
syscall0(montauk::abi::SYS_RESET);
__builtin_unreachable();
inline int reset() {
return (int)syscall0(montauk::abi::SYS_RESET);
}
[[noreturn]] inline void shutdown() {
syscall0(montauk::abi::SYS_SHUTDOWN);
__builtin_unreachable();
inline int shutdown() {
return (int)syscall0(montauk::abi::SYS_SHUTDOWN);
}
inline int suspend() {
@@ -423,6 +431,13 @@ namespace montauk {
return (int)syscall1(montauk::abi::SYS_POWER_REQUEST, (uint64_t)(int64_t)action);
}
// Non-destructive read of the pending request, for a session leader that
// must stand down when something inside its session (the shell's shutdown
// builtin, say) asked for power-off. Returns POWER_REQ_QUERY when idle.
inline int power_request_pending() {
return power_request(montauk::abi::POWER_REQ_PEEK);
}
// Mouse
inline void mouse_state(montauk::abi::MouseState* out) { syscall1(montauk::abi::SYS_MOUSESTATE, (uint64_t)out); }
inline void set_mouse_bounds(int32_t maxX, int32_t maxY) {
@@ -447,6 +462,13 @@ namespace montauk {
inline int spawn_redir(const char* path, const char* args = nullptr) {
return (int)syscall2(montauk::abi::SYS_SPAWN_REDIR, (uint64_t)path, (uint64_t)args);
}
inline int spawn_redir_with_caps(
const char* path, const char* args,
const montauk::abi::SpawnCapabilities& capabilities) {
return (int)syscall3(montauk::abi::SYS_SPAWN_REDIR_CAPS,
(uint64_t)path, (uint64_t)args,
(uint64_t)&capabilities);
}
inline int childio_read(int childPid, char* buf, int maxLen) {
return (int)syscall3(montauk::abi::SYS_CHILDIO_READ, (uint64_t)childPid, (uint64_t)buf, (uint64_t)maxLen);
}
programs/include/montauk/user.h
+10
View File
@@ -219,6 +219,16 @@ namespace user {
return false;
}
inline bool is_admin(const char* username) {
UserInfo users[MAX_USERS];
int count = load_users(users, MAX_USERS);
for (int i = 0; i < count; i++) {
if (montauk::streq(users[i].username, username))
return montauk::streq(users[i].role, "admin");
}
return false;
}
// ---- User management ----
inline bool create_user(const char* username, const char* display_name,