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

Flag	Bit	Allows
STDIO	0x01	Console I/O, basic memory operations
RPATH	0x02	Read-only filesystem access
WPATH	0x04	Write filesystem access
INET	0x08	Network operations
EXEC	0x10	Spawn 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:

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.