[FEATURE] Audit authority, code quality and documentation in powerboxd #1

Open
opened 2026-09-12 07:57:58 +02:00 by erikinkinen · 0 comments
Owner

Problem and motivation

Audit powerboxd throughout Phase 6. Authenticate exact-object authority requests and trusted decisions, with narrow peer queries and explicit grant retirement.

Review each changed boundary at the final published revision. Prioritize security, reliability, then performance.

Proposed behavior and scope

Current inventory: 2 Cargo targets (1 bin, 1 lib); manifests: Cargo.toml. Include explicit and automatically discovered targets, supported features and target-specific configurations.

Inventory every startup/runtime grant and authenticated peer, then success, denial, cancellation, failed transfer, restart and teardown. Trace callers and downstream providers so names, numeric identities and retained aliases never become implicit authority.

Authority, security and reliability

Record each finding's affected revision, invariant, reproduction, owner, regression coverage and resolution. Report suspected vulnerabilities through SECURITY.md and keep sensitive details private. Record a result and rationale for each audit criterion, including caller responsibilities when this component has no process or Rust target.

Acceptance criteria

Checklist
  • Record origin, recipient, object, operations, delegation ceiling, lifetime and aliases for each relevant capability or caller-supplied authority-bearing value.
  • Audit ambient discovery/selectors, cwd/PATH/environment, numeric identities, inherited routes and host fallbacks; require explicit authorized intake.
  • Account for residual authority after success, error, cancellation, timeout, restart, failed transfer and teardown, including fork/exec where implemented.
  • Remove unnecessary endpoints, broad rights, duplicate aliases, provider/admin grants and debug routes.
  • Exercise stale generations, replay, pending replies, forged descriptive identity and object/path resolution races at the owned boundary.
  • Prove independent cleanup attempts and caller-specific error precedence; quarantine or terminate when retained authority cannot be accounted for.
  • Review unsafe/FFI/parser/arithmetic/lifetime/lock/publication invariants and add adversarial coverage where practical.
  • Inventory obsolete APIs, wrappers, fallback/dead paths and duplicate validators with their maintained callers.
  • Migrate callers and delete deprecated contracts/shims in a coherent signed revision graph; reject retired input versions where relevant.
  • Classify each size/count/depth/time bound as ABI, hardware, explicit resource policy or accidental limitation.
  • Test beyond removed boundaries and at allocation/ABI limits while preserving exhaustion errors, denial-of-service controls and bounded waits.
  • Keep every tracked authored code/test/script/workflow file below 1000 physical lines through thematic refactoring.
  • Run the deterministic tracked-source size gate, covering executable fixtures/generators and excluding only genuine non-code data or external payloads.
  • Audit production/test feature and symbol separation, including this repository's effect on rootd test orchestration.
  • Supply changes affecting rootd semantic surface to the maintained same-toolchain baseline; record a justified component-specific applicability result.
  • Check bootstrap ownership and development/release authority parity at this repository's producer/consumer boundary.
  • Use maintained integration#3 profiler evidence before optimizing; preserve live access checks, ownership and success criteria.
  • Audit build/CI inputs, secret handling, private outputs, symlink containment, deletion, subprocess bounds, warnings and host dependencies.
  • meaningful public/private inline documentation, crate/target missing_docs enforcement without blanket allowances or hidden-API escapes, warning-denied private-item rustdoc and an undocumented-public-API negative gate.
  • Validation: Run cargo fmt --all -- --check, strict Clippy, unit/doctests and warning-denied builds/rustdoc for every owned crate/target under default and all valid feature, freestanding/host, SMP and profile combinations; test mutually exclusive combinations separately. Add focused VM regressions for runtime behavior and observe the older catalog and unit tests at the exact published heads.
  • Documentation: update applicable README/ARCHITECTURE/ROADMAP in meta's canonical format and affected technical-manual TeX/API references; keep README evergreen and shared governance byte-identical to meta.
  • Evidence: record exact source/dependency revisions, commands, configurations, real exit status, CI run URLs and results; repeat the audit on final heads and obtain independent review of security closures. No skipped/pending/predecessor result counts as a pass.

Alternatives and tradeoffs

Refactor within the component unless shared semantics justify extracting common code. Preserve regression coverage before deleting superseded paths. Profile before optimizing, and document ABI limits, hardware limits and explicit quotas. Preserve security and reliability requirements.

Matching catalog adoption and real consumer VMs remain requirements; complete realm and full in-guest build acceptance remain open.

Original coherent realm source CI acceptance — 18 September 2026: Signed 8da8a285f390b1dd2c0b6ad450955231dac7fd5a passes CI 40 and CI 39. Coherent catalog publication, actual consumer VMs and full guest-build acceptance remain separate open requirements.

Tracking and rollout

All 38 maintained local checks pass: development/release feature matrices (83 unit tests per selection), strict host/native Clippy, warning-denied builds, private rustdoc, applicable doctests and component-specific checks, formatting and exact dependency-source validation. Native binaries have executable read-only entry pages and no writable executable pages. Original CI47 and CI48 pass; their complete logs are independently reviewed with zero warnings. No unchanged CI was rerun. Coordinated VM configuration/seal/four-client I/O, repeated managed-row reuse, profiler observation and both full builds inside EriX remain open under the phase checklist. This dependency work earns no separate feature-completion credit.

Counted private startup dependency adoption — 24 September 2026.

These host/build results do not establish actual running mediator readiness or retirement, a complete service-image pass, configuration/seal, client I/O, or either required guest rebuild.

Tracking: owning issue, WIP PR and Phase 6 acceptance.

Detailed scope and contracts

Runtime consumer dependency alignment — 15 September 2026

The product catalog, product VM acceptance and guest build remain pending.

Full catalog equality and actual consumer-image validation remain required under Integration regression 68. This dependency checkpoint does not close full lifecycle, frame or self-hosting acceptance.

Full service CPU/profiler VM acceptance and guest builds remain open in Phase 6 completion.

Counted raw program context — producer/consumer design, 1 October 2026

The ordinary prompt boundary must preserve the complete authenticated program entry
without a 240-byte or UTF-8 adapter. This is descriptive data only: Launchd's
entry digest, manifest admission, native scope and object custody remain independent.
Launchd's remaining per-job retained display storage will migrate after this boundary.

Replace the contextual V1 types with PowerboxBeginContextRequestV2 and
TtyPowerboxPromptContextRequestV2 across LibIPC, Launchd, Powerboxd and Ttyd.
The fixed authority-free BEGIN (80 bytes) and prompt (128 bytes), private routes
and answer correlation remain unchanged. V2 context appends job generation u32,
a reserved zero u32 and program length u64; the prompt additionally appends selector
length u64. Prefixes are exactly 96 and 152 bytes. Raw program and then selector
bytes follow. Exact fixed shapes select their fixed codecs; every other shape
selects only V2, without retrying the fixed parser after a contextual failure.
The nonzero legacy contextual length occupies V2's reserved word, so retired V1
contexts reject rather than silently changing interpretation.

Programs use complete absolute normalized raw bytes; generation is nonzero.
Selectors remain complete nonempty NUL-free raw bytes. Counts must fit target
width and exact body extent before borrowing, retaining or encoding. Overflow,
unknown padding, short/long bodies and insufficient output leave storage unchanged.
No opcode, label, generation or byte count creates a capability or changes policy.

Powerbox retains the full original program and selector together in its existing
caller-sized arena, preserves both through compaction and clears retired ranges.
Prompt transport admits the complete body before calling Ttyd. Ttyd escapes each
non-ASCII/control byte, admits the whole rendered review, and retains existing
rollback and visibility-gated secure-input behavior. No truncated prompt or digest
shortcut may authorize consent. Surplus capability receipts retain their existing
independent disposal rules.

Migrate current controls and add raw/long geometry, retired-context refusal,
capacity atomicity, retained arena ownership/compaction and trusted rendering
controls. Document the coordinated immutable revision graph and remaining ordinary
Launchd storage work. Author controls without running tests, builds, checks,
generated documents or CI observation under the current request.

Native SEND and entry-digest
validation return a borrowed complete raw label; ordinary preparation copies it
before transport reuse and admits the sidecar in the remaining exact scratch. Labels create no capability or replacement authority.

Seven new controls cover long raw preparation, reused caller scratch, original
job ownership, capacity/identity refusal, compaction, stale generations, successor
transfer, literal startup geometry and missing/unaddressable budgets.

The containing native migration remains open for remaining provider/name adapters,
complete cross-provider lifetime/refusal controls and coherent runtime catalog
adoption. Existing broad acceptance remains unchanged. Full EriX guest build
generations, external Rust/LLVM rebuilding inside EriX and profiler evidence remain
required and unperformed.

Related records and contracts
Repository Links
docs issue 1, PR 4
integration issue 101, issue 2, PR 12
kernel issue 20
launchd issue 1, PR 2
lib-bootstrap issue 1, PR 2
lib-ipc PR 2
rootd PR 2
ttyd PR 3
## Problem and motivation Audit `powerboxd` throughout Phase 6. Authenticate exact-object authority requests and trusted decisions, with narrow peer queries and explicit grant retirement. Review each changed boundary at the final published revision. Prioritize security, reliability, then performance. ## Proposed behavior and scope Current inventory: 2 Cargo targets (1 bin, 1 lib); manifests: `Cargo.toml`. Include explicit and automatically discovered targets, supported features and target-specific configurations. Inventory every startup/runtime grant and authenticated peer, then success, denial, cancellation, failed transfer, restart and teardown. Trace callers and downstream providers so names, numeric identities and retained aliases never become implicit authority. ## Authority, security and reliability Record each finding's affected revision, invariant, reproduction, owner, regression coverage and resolution. Report suspected vulnerabilities through SECURITY.md and keep sensitive details private. Record a result and rationale for each audit criterion, including caller responsibilities when this component has no process or Rust target. ## Acceptance criteria <details> <summary>Checklist</summary> - [ ] Record origin, recipient, object, operations, delegation ceiling, lifetime and aliases for each relevant capability or caller-supplied authority-bearing value. - [ ] Audit ambient discovery/selectors, cwd/PATH/environment, numeric identities, inherited routes and host fallbacks; require explicit authorized intake. - [ ] Account for residual authority after success, error, cancellation, timeout, restart, failed transfer and teardown, including fork/exec where implemented. - [ ] Remove unnecessary endpoints, broad rights, duplicate aliases, provider/admin grants and debug routes. - [ ] Exercise stale generations, replay, pending replies, forged descriptive identity and object/path resolution races at the owned boundary. - [ ] Prove independent cleanup attempts and caller-specific error precedence; quarantine or terminate when retained authority cannot be accounted for. - [ ] Review unsafe/FFI/parser/arithmetic/lifetime/lock/publication invariants and add adversarial coverage where practical. - [ ] Inventory obsolete APIs, wrappers, fallback/dead paths and duplicate validators with their maintained callers. - [ ] Migrate callers and delete deprecated contracts/shims in a coherent signed revision graph; reject retired input versions where relevant. - [ ] Classify each size/count/depth/time bound as ABI, hardware, explicit resource policy or accidental limitation. - [ ] Test beyond removed boundaries and at allocation/ABI limits while preserving exhaustion errors, denial-of-service controls and bounded waits. - [ ] Keep every tracked authored code/test/script/workflow file below 1000 physical lines through thematic refactoring. - [ ] Run the deterministic tracked-source size gate, covering executable fixtures/generators and excluding only genuine non-code data or external payloads. - [ ] Audit production/test feature and symbol separation, including this repository's effect on rootd test orchestration. - [ ] Supply changes affecting rootd semantic surface to the maintained same-toolchain baseline; record a justified component-specific applicability result. - [ ] Check bootstrap ownership and development/release authority parity at this repository's producer/consumer boundary. - [ ] Use maintained [integration#3](https://git.erikinkinen.fi/erix/integration/issues/3) profiler evidence before optimizing; preserve live access checks, ownership and success criteria. - [ ] Audit build/CI inputs, secret handling, private outputs, symlink containment, deletion, subprocess bounds, warnings and host dependencies. - [ ] meaningful public/private inline documentation, crate/target `missing_docs` enforcement without blanket allowances or hidden-API escapes, warning-denied private-item rustdoc and an undocumented-public-API negative gate. - [ ] Validation: Run `cargo fmt --all -- --check`, strict Clippy, unit/doctests and warning-denied builds/rustdoc for every owned crate/target under default and all valid feature, freestanding/host, SMP and profile combinations; test mutually exclusive combinations separately. Add focused VM regressions for runtime behavior and observe the older catalog and unit tests at the exact published heads. - [ ] Documentation: update applicable README/ARCHITECTURE/ROADMAP in meta's canonical format and affected technical-manual TeX/API references; keep README evergreen and shared governance byte-identical to meta. - [ ] Evidence: record exact source/dependency revisions, commands, configurations, real exit status, CI run URLs and results; repeat the audit on final heads and obtain independent review of security closures. No skipped/pending/predecessor result counts as a pass. </details> ## Alternatives and tradeoffs Refactor within the component unless shared semantics justify extracting common code. Preserve regression coverage before deleting superseded paths. Profile before optimizing, and document ABI limits, hardware limits and explicit quotas. Preserve security and reliability requirements. Matching catalog adoption and real consumer VMs remain requirements; complete realm and full in-guest build acceptance remain open. Original coherent realm source CI acceptance — 18 September 2026: Signed `8da8a285f390b1dd2c0b6ad450955231dac7fd5a` passes [CI 40](https://git.erikinkinen.fi/erix/powerboxd/actions/runs/40) and [CI 39](https://git.erikinkinen.fi/erix/powerboxd/actions/runs/39). Coherent catalog publication, actual consumer VMs and full guest-build acceptance remain separate open requirements. ## Tracking and rollout All 38 maintained local checks pass: development/release feature matrices (83 unit tests per selection), strict host/native Clippy, warning-denied builds, private rustdoc, applicable doctests and component-specific checks, formatting and exact dependency-source validation. Native binaries have executable read-only entry pages and no writable executable pages. Original [CI47](https://git.erikinkinen.fi/erix/powerboxd/actions/runs/47) and [CI48](https://git.erikinkinen.fi/erix/powerboxd/actions/runs/48) pass; their complete logs are independently reviewed with zero warnings. No unchanged CI was rerun. Coordinated VM configuration/seal/four-client I/O, repeated managed-row reuse, profiler observation and both full builds inside EriX remain open under the [phase checklist](https://git.erikinkinen.fi/erix/integration/issues/65). This dependency work earns no separate feature-completion credit. **Counted private startup dependency adoption — 24 September 2026.** These host/build results do not establish actual running mediator readiness or retirement, a complete service-image pass, configuration/seal, client I/O, or either required guest rebuild. Tracking: [owning issue](https://git.erikinkinen.fi/erix/powerboxd/issues/1), [WIP PR](https://git.erikinkinen.fi/erix/powerboxd/pulls/2) and [Phase 6 acceptance](https://git.erikinkinen.fi/erix/integration/issues/65). <details> <summary>Detailed scope and contracts</summary> ### Runtime consumer dependency alignment — 15 September 2026 The product catalog, product VM acceptance and guest build remain pending. Full catalog equality and actual consumer-image validation remain required under [Integration regression 68](https://git.erikinkinen.fi/erix/integration/issues/68). This dependency checkpoint does not close full lifecycle, frame or self-hosting acceptance. Full service CPU/profiler VM acceptance and guest builds remain open in [Phase 6 completion](https://git.erikinkinen.fi/erix/integration/issues/65). ### Counted raw program context — producer/consumer design, 1 October 2026 The ordinary prompt boundary must preserve the complete authenticated program entry without a 240-byte or UTF-8 adapter. This is descriptive data only: Launchd's entry digest, manifest admission, native scope and object custody remain independent. Launchd's remaining per-job retained display storage will migrate after this boundary. Replace the contextual V1 types with PowerboxBeginContextRequestV2 and TtyPowerboxPromptContextRequestV2 across LibIPC, Launchd, Powerboxd and Ttyd. The fixed authority-free BEGIN (80 bytes) and prompt (128 bytes), private routes and answer correlation remain unchanged. V2 context appends job generation u32, a reserved zero u32 and program length u64; the prompt additionally appends selector length u64. Prefixes are exactly 96 and 152 bytes. Raw program and then selector bytes follow. Exact fixed shapes select their fixed codecs; every other shape selects only V2, without retrying the fixed parser after a contextual failure. The nonzero legacy contextual length occupies V2's reserved word, so retired V1 contexts reject rather than silently changing interpretation. Programs use complete absolute normalized raw bytes; generation is nonzero. Selectors remain complete nonempty NUL-free raw bytes. Counts must fit target width and exact body extent before borrowing, retaining or encoding. Overflow, unknown padding, short/long bodies and insufficient output leave storage unchanged. No opcode, label, generation or byte count creates a capability or changes policy. Powerbox retains the full original program and selector together in its existing caller-sized arena, preserves both through compaction and clears retired ranges. Prompt transport admits the complete body before calling Ttyd. Ttyd escapes each non-ASCII/control byte, admits the whole rendered review, and retains existing rollback and visibility-gated secure-input behavior. No truncated prompt or digest shortcut may authorize consent. Surplus capability receipts retain their existing independent disposal rules. Migrate current controls and add raw/long geometry, retired-context refusal, capacity atomicity, retained arena ownership/compaction and trusted rendering controls. Document the coordinated immutable revision graph and remaining ordinary Launchd storage work. Author controls without running tests, builds, checks, generated documents or CI observation under the current request. Native SEND and entry-digest validation return a borrowed complete raw label; ordinary preparation copies it before transport reuse and admits the sidecar in the remaining exact scratch. Labels create no capability or replacement authority. Seven new controls cover long raw preparation, reused caller scratch, original job ownership, capacity/identity refusal, compaction, stale generations, successor transfer, literal startup geometry and missing/unaddressable budgets. The containing native migration remains open for remaining provider/name adapters, complete cross-provider lifetime/refusal controls and coherent runtime catalog adoption. Existing broad acceptance remains unchanged. Full EriX guest build generations, external Rust/LLVM rebuilding inside EriX and profiler evidence remain required and unperformed. </details> <details> <summary>Related records and contracts</summary> | Repository | Links | | --- | --- | | docs | [issue 1](https://git.erikinkinen.fi/erix/docs/issues/1), [PR 4](https://git.erikinkinen.fi/erix/docs/pulls/4) | | integration | [issue 101](https://git.erikinkinen.fi/erix/integration/issues/101), [issue 2](https://git.erikinkinen.fi/erix/integration/issues/2), [PR 12](https://git.erikinkinen.fi/erix/integration/pulls/12) | | kernel | [issue 20](https://git.erikinkinen.fi/erix/kernel/issues/20) | | launchd | [issue 1](https://git.erikinkinen.fi/erix/launchd/issues/1), [PR 2](https://git.erikinkinen.fi/erix/launchd/pulls/2) | | lib-bootstrap | [issue 1](https://git.erikinkinen.fi/erix/lib-bootstrap/issues/1), [PR 2](https://git.erikinkinen.fi/erix/lib-bootstrap/pulls/2) | | lib-ipc | [PR 2](https://git.erikinkinen.fi/erix/lib-ipc/pulls/2) | | rootd | [PR 2](https://git.erikinkinen.fi/erix/rootd/pulls/2) | | ttyd | [PR 3](https://git.erikinkinen.fi/erix/ttyd/pulls/3) | </details>
erikinkinen changed title from [FEATURE] [P02.R63] Audit authority, code quality and documentation in powerboxd to [FEATURE] Audit authority, code quality and documentation in powerboxd 2026-09-12 08:02:38 +02:00
erikinkinen added this to the Alpha 1 milestone 2026-10-30 09:35:08 +01:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
erix/powerboxd#1
No description provided.