powerboxd

powerboxd is EriX's trusted object-bound authority broker. It resolves an exact selector inside an explicitly transferred scope, applies authenticated session policy to routine or exceptional requests, correlates any trusted terminal prompt, and tracks the installed grant through consumption, expiry, cancellation, and revocation cleanup.

Running programs can also request grants through launchd's exact-job broker. In runtime-reply mode, powerboxd derives a revocable alias of the already resolved SEND-only object and exports it once through an authenticated IPC reply. Launchd delivers that alias to the blocked running caller; no retained foreign-CSpace installer is required. Policy, trusted review, one-shot/expiry cleanup and exact VFS object retirement remain mandatory.

An exact scoped VFS NOT_FOUND reply with the matching missing-object failure class is retained separately from denial. Only after request authority cleanup does its receipt-free decision report NOT_FOUND; transport absence, missing internal identities, policy/user denial and uncertain cleanup cannot produce that result. It grants no permission to create a replacement object.

EriX is a clean-room, capability-based microkernel operating system written entirely in Rust.

See:

• docs for system architecture and the technical manual
• lib-ipc for canonical powerbox, trusted-prompt, operation, lifetime, and object-class records
• lib-capabi for exact powerboxd endpoint routes and startup transfer policy

Purpose of This Repository

This repository provides a no_std, allocation-free semantic core, typed private-peer adapters, and the powerboxd syscall executable for exact-object authority decisions. The executable authenticates its startup inventory, constructs every mutable region described by PBX1 from one deployment-patched arena, and supplies only narrow syscall transport, slot-query, and exact slot-deletion effects.

The maintained responsibilities are:

• reserve exact caller-sized storage for streamed selector requests
• reserve an authenticated transient destination during authority-free begin and accept the request scope only as the sole exact commit-time receipt
• keep selector bytes non-authoritative until SHA-256 commit and scoped resolution
• bind resolver evidence to operation, class, selector, scope, and object identity
• authenticate exact vfsd object and procd revocation receipts in generational transient slots
• identify pre-authorized routine requests separately from exceptional deny-or-prompt requests and apply exact ttyd session policy to both
• admit exact entry metadata reads and touch updates only as one-shot directory-entry requests; never widen them to generic file metadata or a longer-lived grant
• correlate trusted prompts to the session, realm, job, request, and object
• record procd installation as a generational, operation-bound grant
• publish the exact installed row as receipt-free descriptive data to ttyd before exposing approval, then reconcile its exact removal on every terminal path without delaying capability revocation
• revoke one-shot, invocation, job, and cancelled grants through exact procd cleanup, then retire the corresponding vfsd receiver/provider object
• retain partial decisions and authority slots under retryable backpressure
• expose approved, denied, cancelled, and pending responses without authority leakage
• retain every approved, denied, or cancelled decision until an authority-free correlation wake is successfully queued to launchd; retry transient notify backpressure without polling or discarding terminal state
• dispatch every public operation through one canonical authority-partitioned frame parser and defer terminal record retirement until reply delivery
• delete unwanted or malformed peer receipts before releasing their exact destinations, with cleanup failure taking precedence

Selectors, identifiers, digests, and numeric slots are data, not authority. The runtime must retain the real capability for every tracked slot until exact installation, transfer, or deletion succeeds.

Clean-Room Policy

EriX follows a strict clean-room philosophy:

• No external source code may be copied.
• No external Rust crates are allowed.
• No code generation tools that embed third-party code.
• All code must be authored within the project.

Violations will result in rejection of the contribution.

License

All EriX repositories are licensed under the ISC License.

Development Model

The core forbids unsafe code, denies missing public documentation, and owns no ambient authority. Requests, selectors, grants, prompts, decisions, receipts, resolutions, replies, expirations, and cleanup records use authenticated deployment storage rather than private logical-object ceilings. Full storage returns explicit backpressure without dropping authority or terminal state.

Repository validation requires:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
RUSTFLAGS="-D warnings" cargo test --all-targets --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
RUSTFLAGS="-D warnings" cargo check --lib \
  --target x86_64-unknown-none --all-features
cargo clippy --target x86_64-unknown-none --lib --bin powerboxd \
  --all-features -- -D warnings
RUSTFLAGS="-D warnings -C link-arg=-Tlinker.ld" cargo build \
  --target x86_64-unknown-none --bin powerboxd --features powerboxd-runtime
RUSTFLAGS="-D warnings -C link-arg=-Tlinker.ld" cargo build \
  --target x86_64-unknown-none --bin powerboxd --features powerboxd-runtime \
  --release

Status

Implemented:

• exact PBX1 startup and live capability-inventory validation
• blocking receive completion only when a public capability-transfer caller is waiting at the kernel rendezvous
• process-created local request endpoint validation separated from the four root-transferred peer routes; no startup self-transfer or primary control
• authenticated post-mount ext4 materialization and typed readiness through loaderd, dynlinkd, procd, and rootd without a boot-store copy
• sequential selector storage and SHA-256 commit verification
• resolver, session-policy, and trusted-prompt evidence correlation
• interactive-denial behavior with no output authority
• generational grants with one-shot consumption, expiry, and cancellation
• deterministic, lossless cleanup of request scope, resolved object, and grant revocation authority
• distinct service-local exit statuses for public receive/dispatch/reply, cleanup, retained request progression, and notification failures
• exact authenticated storage-shape validation
• typed vfsd resolution, ttyd session-policy, and procd grant-install calls
• authenticated vfsd object-detach calls that transfer the exact approved alias back while preserving child authority, plus receipt-free terminal object retirement after exact procd revocation
• full-transport caller-owned reply storage that permits deletion of every kernel-normalized unwanted receipt
• public begin/commit intake that publishes only a receiver-local scope slot as data, then authenticates the exact endpoint-send receipt before resolution
• runtime-neutral public BEGIN, selector, COMMIT, decision, cancellation, and one-shot-consumption/expiration dispatch with exhaustive non-COMMIT receipt cleanup, cleanup-pending status, and post-reply progress/retirement signals
• one-transition retained peer progression through scoped resolution, session policy, deferred trusted prompt, preflighted grant installation, and exact object/scope/revocation cleanup with retryable backpressure, including absence-proven release of a scope reserved by a pre-COMMIT cancellation and classified fail-stop for permanent kernel cleanup rejection
• authority-free ttyd trusted-prompt transport that authenticates every echoed identity and deletes any unexpected reply receipt
• exact contextual BEGIN and prompt bodies preserve the launchd-authenticated canonical program entry, job generation, and digest-checked scope-relative selector in caller-owned storage; display labels never select authority
• authority-free empty ttyd RETRY before prompt admission preserves the exact contextual request while earlier physical input drains; accepted calls still wait for their fully correlated trusted answer
• receipt-free active/remove grant-view transport over the existing private ttyd route, with exact generational echoes, retryable publication, and exhaustive unexpected-receipt cleanup
• exact deployment-patched arena construction for every authenticated PBX1 capacity, including otherwise not-yet-consumed retained-record pools, with type-layout and page-extent mismatch failure before startup readiness
• an authenticated powerboxd_entry syscall runtime with canonical public receive/reply framing, exact private-peer calls, bounded round-robin request scanning, cleanup and notification fairness, retrying decision-ready wakes, and terminal retirement only after reply delivery

Lifecycle use of the remaining reserved prompt, policy, decision, receipt, resolution, and reply pools plus focused approval/denial VM validation remains in progress. Exact launchd-driven invocation/job expiry and powerboxd's revocation-to-vfsd-retirement chain are implemented. powerboxd must be installed on ext4 and started through the authenticated loaderd/dynlinkd/procd path after the root filesystem is mounted; it is not a boot.img service.

Governance Principles

powerboxd governs routine and exceptional object-bound grants, not shell language, terminal rendering, filesystem policy, process creation, or general capability discovery.

• A request endpoint permits asking for authority; it does not imply approval.
• BEGIN transfers no authority. Its receiver-local destination number only identifies the exact authenticated transient reservation that COMMIT must populate with one endpoint-send receipt.
• Resolution occurs only through an exact transferred namespace or object scope.
• Session policy may allow, deny, or request a prompt; promptability itself is never authority.
• A prompt is valid only through ttyd's trusted terminal path and must bind the exact object shown to the user.
• procd installs only the requested slot in the exact staged process generation and returns a distinct manage-only revocation handle retained until terminal cleanup; its staging install grant is never accepted as revocation authority.
• An installed grant is not reported approved until ttyd acknowledges its full descriptive ACTIVE row. Grant IDs and installed slots remain data; the call transfers no authority.
• Terminal decisions are not published while request-owned capabilities remain.
• Approved-object cleanup asks vfsd to authenticate and detach powerboxd's transferred alias while preserving the installed child's receiver/provider. Terminal cleanup first deletes the exact manage-only procd revocation grant, independently reconciles the full REMOVE row with ttyd, then sends receipt-free full-identity retirement to vfsd; only exact acknowledgements permit the grant/request generation to retire.
• Generation-zero cancellation is accepted only for one globally unambiguous live correlation whose approval reply may have been lost. A known grant and every expiration remain exact nonzero-generation operations.
• Grant slot reuse changes a nonzero generation, rejecting stale consumption and cancellation requests.
• Git dependencies use full 40-character commit rev pins. Integration source revisions and CI caches preserve those identities, with no branch-head or synthetic-commit substitution.

Library Boundaries

• lib-ipc owns every numeric operation, discriminant, and wire record.
• lib-capabi owns powerboxd's endpoint provenance, rights, and local slots.
• lib-bootstrap owns service identity and authenticated PBX1 storage geometry.
• lib-sha2 owns canonical SHA-256 computation.
• The executable owns only its startup-transferred endpoints, explicitly received per-request capabilities, syscall I/O, and the packaged arena. The semantic crate authenticates typed peer replies and drives exact deletion through supplied callbacks.

Contact

Development occurs in the EriX organization. Decisions and rationale are recorded in issues and design documents.

Maintainers can be reached at admin@erikinkinen.fi.