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

New issue

Open

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

erikinkinen commented

2026-09-12 07:58:02 +02:00

Owner

Problem and motivation

This issue tracks continuous Phase 6 audit closure for vfsd. Mediate mount namespaces and exact filesystem-object grants without letting descriptive paths authorize operations.

An initial inventory is not a security or documentation closure claim. Evidence must follow each changed boundary through final heads, with priority security, reliability, then performance.

Proposed behavior and scope

Current inventory: 1 Cargo target (1 bin); 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

Maintain a finding register with public finding references, exact revisions, invariants, reproduction, owners, regression tests and closure evidence. Publish only non-sensitive status here; suspected vulnerabilities follow SECURITY.md. Each dimension below needs its own result and rationale; an absent daemon or current Rust target is not a blanket exemption.

Acceptance criteria

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

Use cohesive local refactoring or a justified shared extraction only after identifying real common semantics and authority boundaries. Remove superseded paths after preserving maintained coverage. Profile before optimization; document unavoidable ABI/hardware limits and explicit quotas rather than weakening security for speed.

Coherent realm image service prerequisites — 18 September 2026: Signed d87c9732f1eeb47356933e53e381a00d96a30a5c selects the original shared wire/startup dependency graph. Direct Rust implementation bytes are unchanged. All 6 default, all-feature and separate production development/release configurations pass 136 unit tests per configuration, strict host/native Clippy and freestanding linking with fatal linker warnings. Formatting, private-item rustdoc and Markdown pass, with zero warnings. Original push/PR CI is under observation. Matching catalog adoption and real consumer VMs remain requirements; complete realm and full in-guest build acceptance remain open.

Tracking and rollout

Runtime consumer dependency alignment — 15 September 2026

Signed bd013ca3cb7d42443bcf9f47c3ff807fbcdbd7e8 aligns the existing dependency selections with the original signed runtime graph. This checkpoint changes Cargo selections and the roadmap; this repository's Rust implementation files are unchanged. Formatting, strict Clippy, private rustdoc and canonical documentation checks pass without warnings. Default/all-feature development/release tests pass 136 default / 136 all-feature tests. Independent production configurations also pass strict host/native Clippy and native builds: vfsd-runtime: 136 development / 136 release tests. There are 8 supported native builds in total. Both emitted runtime/smoke provider-read fixed-frame proofs and their negative fixtures pass under the unchanged deployment stack limit. Indirect control flow and descendant/recursive usage remain outside this proof. Push/review CI 82/83 passes with complete classified logs and no final warnings. The product catalog, product VM acceptance and guest build remain pending. Review: #3.

Parent work: erix/integration#2 and erix/docs#1.
Branch: feature/posix-compat; update linked WIP PRs after coherent signed checkpoints using canonical CONTRIBUTING.md messages.
Baseline revision: 6e05c765d1cf2c2b2bb667bba925632ccafa0775; refresh component/dependency heads and their own CI evidence as implementation advances.
Cross-repository dependencies remain full lowercase commit hashes; update the selected graph deliberately. This issue does not authorize merges, release tags or replacement of published images.

Coherent dependency checkpoint — 20 September 2026: signed/pushed commit 4c5e73237bdcb0f5769e5b5bd1ff70cb695e9142 aligns original shared dependency pins with the explicit installer-rights contract. Only the manifest and roadmap change; local implementation, APIs and authority policy are unchanged. Four strict 136-unit configurations, four native builds with the maintained linker layout, host/native Clippy, formatting, private rustdoc and dependency checks pass without warnings. Original CI 86/87 passes with four complete hashed logs (149,192 bytes), zero warning candidates.

Full catalog equality and actual consumer-image validation remain required under Integration regression 68. The broader work remains tracked by phase completion, including native external Rust/LLVM/runtime rebuilding and both complete EriX-in-EriX generations. This dependency checkpoint does not close full lifecycle, frame or self-hosting acceptance.

Acknowledged terminal service dependencies — 21 September 2026: signed adb1f3aa6f866e0918c103c4f4be93a5bab820e7 selects the original shared libraries for repeated terminal observation, exact acknowledgement and final CPU measurements under Kernel design 20. All 4 strict 136-test selected development/release feature configurations, warning-denied host/native builds with the maintained linker layout, host/native Clippy, private rustdoc, applicable doctests, formatting and dependency/Markdown checks pass. All authored code remains below 1,000 lines. Original CI 88, 89 passes; complete hashed logs total 149,253 bytes with zero warning candidates. Full service CPU/profiler VM acceptance and guest builds remain open in Phase 6 completion.

Explicit provider-frame tool custody — 21 September 2026:

Signed 378181a5840fab0433e350cf6519e729f9283fdc requires explicit absolute selections for the regular disassembler, original Integration ownership helpers and a new evidence directory. There is no executable-name fallback or inherited caller environment; the selected child receives only a fixed locale, closed stdin and the ELF directory. The existing process owner enforces the unchanged thirty-second deadline, an explicit output budget (32 MiB by default) and descendant cleanup. Tool/helper identities, streams, original exit/failure status and cleanup outcomes are retained. Unexpected diagnostics fail proof admission.

All thirteen parser controls and eight actual tool-boundary controls pass, including environment/PATH shadowing, rejected tool and input leaves, cached helper substitution, nonzero execution, diagnostics, output refusal and evidence preservation. Actual runtime and smoke PIC checks each measure 167,632 fixed-frame bytes under the unchanged 245,760-byte ceiling and 262,144-byte deployment stack. Four prior strict 136-test Rust configurations remain applicable to byte-identical Rust, manifest and linker inputs. Formatting, workflow syntax, dependency policy and component Markdown pass; the initial documentation lint errors and their corrections remain retained.

The CLI, CI, README and architecture are updated together; the technical manual documents the same boundary. Original CI 90/91 is monitored separately. Local byte receipts do not isolate hostile writers sharing the host account or extend the fixed-frame gate to complete indirect/recursive stack proof. Full service VM and native external-toolchain/guest-build acceptance remain open in Phase 6 completion.

Original explicit-tool CI acceptance — 21 September 2026: signed 378181a5840fab0433e350cf6519e729f9283fdc passes both original CI 90/91. Four complete hashed logs total 158,176 bytes with zero warnings. The actual emitted runtime/smoke gates, 13 parser controls and 8 tool-boundary controls pass. This closes the bounded host-tool correction; full guest and whole-program frame acceptance remain separate.

## Problem and motivation This issue tracks continuous Phase 6 audit closure for `vfsd`. Mediate mount namespaces and exact filesystem-object grants without letting descriptive paths authorize operations. An initial inventory is not a security or documentation closure claim. Evidence must follow each changed boundary through final heads, with priority security, reliability, then performance. ## Proposed behavior and scope Current inventory: 1 Cargo target (1 bin); 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 Maintain a finding register with public finding references, exact revisions, invariants, reproduction, owners, regression tests and closure evidence. Publish only non-sensitive status here; suspected vulnerabilities follow SECURITY.md. Each dimension below needs its own result and rationale; an absent daemon or current Rust target is not a blanket exemption. ## Acceptance criteria - [ ] 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. ## Alternatives and tradeoffs Use cohesive local refactoring or a justified shared extraction only after identifying real common semantics and authority boundaries. Remove superseded paths after preserving maintained coverage. Profile before optimization; document unavoidable ABI/hardware limits and explicit quotas rather than weakening security for speed. Coherent realm image service prerequisites — 18 September 2026: Signed `d87c9732f1eeb47356933e53e381a00d96a30a5c` selects the original shared wire/startup dependency graph. Direct Rust implementation bytes are unchanged. All 6 default, all-feature and separate production development/release configurations pass 136 unit tests per configuration, strict host/native Clippy and freestanding linking with fatal linker warnings. Formatting, private-item rustdoc and Markdown pass, with zero warnings. Original push/PR CI is under observation. Matching catalog adoption and real consumer VMs remain requirements; complete realm and full in-guest build acceptance remain open. ## Tracking and rollout ### Runtime consumer dependency alignment — 15 September 2026 Signed `bd013ca3cb7d42443bcf9f47c3ff807fbcdbd7e8` aligns the existing dependency selections with the original signed runtime graph. This checkpoint changes Cargo selections and the roadmap; this repository's Rust implementation files are unchanged. Formatting, strict Clippy, private rustdoc and canonical documentation checks pass without warnings. Default/all-feature development/release tests pass 136 default / 136 all-feature tests. Independent production configurations also pass strict host/native Clippy and native builds: `vfsd-runtime`: 136 development / 136 release tests. There are 8 supported native builds in total. Both emitted runtime/smoke provider-read fixed-frame proofs and their negative fixtures pass under the unchanged deployment stack limit. Indirect control flow and descendant/recursive usage remain outside this proof. Push/review CI 82/83 passes with complete classified logs and no final warnings. The product catalog, product VM acceptance and guest build remain pending. Review: https://git.erikinkinen.fi/erix/vfsd/pulls/3. - Parent work: https://git.erikinkinen.fi/erix/integration/issues/2 and https://git.erikinkinen.fi/erix/docs/issues/1. - Branch: `feature/posix-compat`; update linked WIP PRs after coherent signed checkpoints using canonical CONTRIBUTING.md messages. - Baseline revision: `6e05c765d1cf2c2b2bb667bba925632ccafa0775`; refresh component/dependency heads and their own CI evidence as implementation advances. - Cross-repository dependencies remain full lowercase commit hashes; update the selected graph deliberately. This issue does not authorize merges, release tags or replacement of published images. Coherent dependency checkpoint — 20 September 2026: signed/pushed commit [4c5e73237bdcb0f5769e5b5bd1ff70cb695e9142](https://git.erikinkinen.fi/erix/vfsd/commit/4c5e73237bdcb0f5769e5b5bd1ff70cb695e9142) aligns original shared dependency pins with the explicit installer-rights contract. Only the manifest and roadmap change; local implementation, APIs and authority policy are unchanged. Four strict 136-unit configurations, four native builds with the maintained linker layout, host/native Clippy, formatting, private rustdoc and dependency checks pass without warnings. Original CI 86/87 passes with four complete hashed logs (149,192 bytes), zero warning candidates. Full catalog equality and actual consumer-image validation remain required under [Integration regression 68](https://git.erikinkinen.fi/erix/integration/issues/68). The broader work remains tracked by [phase completion](https://git.erikinkinen.fi/erix/integration/issues/65), including native external Rust/LLVM/runtime rebuilding and both complete EriX-in-EriX generations. This dependency checkpoint does not close full lifecycle, frame or self-hosting acceptance. Acknowledged terminal service dependencies — 21 September 2026: signed [adb1f3aa6f866e0918c103c4f4be93a5bab820e7](https://git.erikinkinen.fi/erix/vfsd/commit/adb1f3aa6f866e0918c103c4f4be93a5bab820e7) selects the original shared libraries for repeated terminal observation, exact acknowledgement and final CPU measurements under [Kernel design 20](https://git.erikinkinen.fi/erix/kernel/issues/20). All 4 strict 136-test selected development/release feature configurations, warning-denied host/native builds with the maintained linker layout, host/native Clippy, private rustdoc, applicable doctests, formatting and dependency/Markdown checks pass. All authored code remains below 1,000 lines. Original CI [88](https://git.erikinkinen.fi/erix/vfsd/actions/runs/88), [89](https://git.erikinkinen.fi/erix/vfsd/actions/runs/89) passes; complete hashed logs total 149,253 bytes with zero warning candidates. Full service CPU/profiler VM acceptance and guest builds remain open in [Phase 6 completion](https://git.erikinkinen.fi/erix/integration/issues/65). Explicit provider-frame tool custody — 21 September 2026: Signed [378181a5840fab0433e350cf6519e729f9283fdc](https://git.erikinkinen.fi/erix/vfsd/commit/378181a5840fab0433e350cf6519e729f9283fdc) requires explicit absolute selections for the regular disassembler, original Integration ownership helpers and a new evidence directory. There is no executable-name fallback or inherited caller environment; the selected child receives only a fixed locale, closed stdin and the ELF directory. The existing process owner enforces the unchanged thirty-second deadline, an explicit output budget (32 MiB by default) and descendant cleanup. Tool/helper identities, streams, original exit/failure status and cleanup outcomes are retained. Unexpected diagnostics fail proof admission. All thirteen parser controls and eight actual tool-boundary controls pass, including environment/PATH shadowing, rejected tool and input leaves, cached helper substitution, nonzero execution, diagnostics, output refusal and evidence preservation. Actual runtime and smoke PIC checks each measure 167,632 fixed-frame bytes under the unchanged 245,760-byte ceiling and 262,144-byte deployment stack. Four prior strict 136-test Rust configurations remain applicable to byte-identical Rust, manifest and linker inputs. Formatting, workflow syntax, dependency policy and component Markdown pass; the initial documentation lint errors and their corrections remain retained. The CLI, CI, README and architecture are updated together; the technical manual documents the same boundary. Original CI [90](https://git.erikinkinen.fi/erix/vfsd/actions/runs/90)/[91](https://git.erikinkinen.fi/erix/vfsd/actions/runs/91) is monitored separately. Local byte receipts do not isolate hostile writers sharing the host account or extend the fixed-frame gate to complete indirect/recursive stack proof. Full service VM and native external-toolchain/guest-build acceptance remain open in [Phase 6 completion](https://git.erikinkinen.fi/erix/integration/issues/65). Original explicit-tool CI acceptance — 21 September 2026: signed [378181a5840fab0433e350cf6519e729f9283fdc](https://git.erikinkinen.fi/erix/vfsd/commit/378181a5840fab0433e350cf6519e729f9283fdc) passes both original CI [90](https://git.erikinkinen.fi/erix/vfsd/actions/runs/90)/[91](https://git.erikinkinen.fi/erix/vfsd/actions/runs/91). Four complete hashed logs total 158,176 bytes with zero warnings. The actual emitted runtime/smoke gates, 13 parser controls and 8 tool-boundary controls pass. This closes the bounded host-tool correction; full guest and whole-program frame acceptance remain separate.

erikinkinen added the

labels

2026-09-12 07:58:02 +02:00

erikinkinen referenced this issue from erix/integration

2026-09-12 08:02:00 +02:00

[FEATURE] Audit and refactor authority, lifecycle and code quality across every repository #2

erikinkinen changed title from ~~[FEATURE] [P02.R72] Audit authority, code quality and documentation in vfsd~~ to [FEATURE] Audit authority, code quality and documentation in vfsd

2026-09-12 08:02:41 +02:00

erikinkinen referenced this issue

2026-09-12 12:53:48 +02:00

WIP: Harden VFS frame validation and service integration #3

erikinkinen referenced this issue from erix/integration

2026-09-19 11:36:52 +02:00

[FEATURE] Track Phase 6 POSIX compatibility and full EriX self-hosting #65