Nexus OS Docs

Appearance

Pledge System ​

Complete

The Pledge system is Nexus OS's adaptation of OpenBSD's pledge(2) and unveil(2) — a one-way ratchet that restricts a process to a minimum privilege set.

How Pledge Works ​

A fiber pledges a set of permissions at startup (declared in its BKDL manifest) or at any point during execution. Once pledged, the permission set can only shrink — it can never grow.

Fiber starts with:     STDIO | RPATH | WPATH | INET | EXEC
Fiber pledges to:      STDIO | RPATH | INET
After pledge:          STDIO | RPATH | INET  (WPATH and EXEC removed forever)

Any syscall that requires a revoked permission triggers a capability fault. The fiber is killed.

Pledge Permissions ​

FlagBitAllows
STDIO0x01Console I/O, basic memory operations
RPATH0x02Read-only filesystem access
WPATH0x04Write filesystem access
INET0x08Network operations
EXEC0x10Spawn new fibers

The top two bits [63:62] of the pledge mask encode the fiber's scheduling spectrum (Photon/Matter/Gravity/Void).

Unveil — Filesystem Visibility ​

Unveil restricts which filesystem paths a fiber can see:

unveil("/Data/users/markus", "r")   # Read-only access to user dir
unveil("/Bus/net", "rw")            # Read-write access to network endpoints
unveil(NULL, NULL)                  # Lock: no more unveil calls allowed

After the final unveil(NULL, NULL) call, the fiber can only see the paths it explicitly revealed. All other paths are invisible — they don't return "permission denied", they return "not found". The fiber cannot even discover that other paths exist.

Hardware Enforcement ​

Pledge restrictions are enforced by the kernel at syscall time, but the underlying isolation is enforced by hardware:

  • RISC-V: Physical Memory Protection (PMP) registers limit accessible memory regions
  • ARM64: Memory Protection Unit (MPU) or Stage-2 page tables restrict access
  • x86_64: Page table permissions enforce read/write/execute boundaries

This means pledge is not just a software check — it is backed by silicon. A compromised fiber that tries to bypass pledge through return-oriented programming or other techniques will hit a hardware fault.

Pledge in the Boot Manifest ​

NPL and NPK manifests declare their pledge requirements in BKDL:

ini
manifest {
  pledge "STDIO" "RPATH" "INET"
  unveil "/Bus/net" "rw"
  unveil "/Data/apps/myapp" "r"
}

The kernel reads these declarations at fiber spawn time and configures the capability set and hardware protections accordingly. A manifest that requests more privileges than its parent can grant is rejected.

Pledge Widen — Always Denied ​

There is no mechanism to widen a pledge after it has been set. The system will log the attempt to ProvChain and kill the fiber. This is by design — it prevents privilege escalation attacks where a compromised process tries to grant itself additional permissions.