Specify filesystem sharing, component identities, and permissions with implementation drift checks

Motivation

AWF's filesystem access rules are spread across the baseline sandbox mount policy, per-component mount builders, runtime-specific export planners, host directory setup, and container entrypoints. Existing documentation explains portions of this behavior, but there is no single contract describing which host directories are shared with which components, at which destinations, under which identities, and with which permissions.

This makes security review, debugging permission failures, and assessing the impact of changes unnecessarily difficult. A generated Compose file helps identify mounts for a particular Docker run, but does not capture all ownership changes, post-entrypoint identities, or microVM enforcement.

Create one Filesystem Sharing Contract document that combines explanatory semantics with implementation-derived access tables and explicit verification coverage. This issue proposes documentation and consistency mechanisms; it does not authorize changing filesystem access defaults or widening component access.

Existing sources and documentation

• src/config/sandbox-mount-policy.json and src/config/mount-policy.ts: baseline allow/deny paths; not a complete component permissions inventory.
• src/services/agent-volumes/volume-builder.ts and its helpers: Compose agent mounts, credential overlays, custom mounts, and write-policy application.
• src/services/*: component-specific mounts and security settings.
• src/compose-generator.ts and src/services/optional-services.ts: final assembly, conditional services, and topology-specific transformations.
• src/workdir-setup.ts, src/chroot-home-setup.ts, src/log-directory-setup.ts, and container entrypoints: ownership, modes, and identity transitions.
• Runtime-specific planners, including src/cloud-hypervisor/exports.ts and host mount-tree enforcement, plus sbx and NVX paths.
• Existing documentation: docs/mount-policy.md, docs/awf-config-spec.md §4.1, docs/environment.md, docs/enclaves-architecture.md, and runtime security/architecture documents.

docs/selective-mounting.md currently contains examples showing wholesale $HOME mounts alongside statements that the real home is not mounted wholesale. Reconcile these directly related examples and link relevant existing documents to the new contract rather than adding another competing inventory.

Required specification content

1. Scope and semantics

Distinguish explicitly:

• Visibility: whether a source is reachable by the component, including alternate destinations and aliases.
• Mount access: read-only/read-write, overlays, tmpfs, named volumes, and runtime-specific export enforcement.
• Process authority: effective UID/GID, supplementary groups, capabilities, and relevant confinement.
• Host permissions: source ownership and mode bits, inheritance/preservation, and setup-time changes.

A rw mount permits writes at the mount boundary; it does not override Unix discretionary access controls. A ro mount at one destination does not establish a global write prohibition if the same source is exposed through another writable path.

Clearly separate intended requirements from observed implementation behavior and mark unsupported or unverified configurations. Do not claim that the shared JSON policy governs all runtimes: Cloud Hypervisor uses its own production export path, for example.

2. Component identity table

For each supported component/runtime combination, describe:

• Startup identity versus final workload identity.
• UID/GID selection and fallback rules, supplementary groups, and relevant privilege/capability changes.
• Whether IDs are container IDs, host IDs, or mapped IDs; explain user-namespace assumptions where applicable.
• Which source defines or changes the identity: image metadata, Compose settings, host launcher, or entrypoint.

Include the primary agent, Squid, API/CLI/DoH proxies, iptables-init, optional enclave services/executors, and other applicable services such as sysroot staging or model routing. Enumerate the actual supported component set during implementation rather than assuming this list is exhaustive.

3. Filesystem access matrix

Use one row per component-to-source/destination relationship, not one row per directory. Include:

Field	Required meaning
Runtime / activation condition	Backend, feature flag, topology, or prerequisite enabling the relationship
Source	Host path expression, named volume, generated content, or ephemeral storage
Component and destination	Consumer and its actual destination, including pre-/post-chroot interpretation where necessary
Process identity	Reference to the applicable identity-table entry
Ownership / permissions	Owner/group and mode, or an explicit rule that existing ownership/modes are preserved
Mount/export access	ro/rw, narrowing policy, overlays, and applicable enforcement mechanism
Lifecycle	Creator, setup-time mutation, cleanup/preservation behavior
Purpose / implementation source	Why the share exists and the code responsible

Use symbolic expressions for dynamic directories and UIDs, with definitions. Distinguish creation modes from final modes after explicit chmod/chown; account for umask and existing sources. Cover files, sockets, and virtual filesystems as well as directories where they affect the access boundary.

Document important negative guarantees, including host credential exclusions and enclave-private paths that must not become agent-visible. Explain filesystem.allowWrite, operational exceptions, and backend-specific support rather than implying identical behavior everywhere.

Keeping the contract consistent with implementation

Recommended architecture

Prefer a typed, implementation-owned sharing plan that runtime configuration, host preparation, and documentation generation consume. It should capture source, destination, consumer, mount access, identity, ownership/setup requirements, and activation conditions. Avoid a separate handwritten permissions manifest used only to generate documentation.

Adopt this incrementally: initially derive tables from the existing final builders/planners, explicitly identify information they cannot yet provide, and consolidate identity/ownership setup into the shared representation as practical. A broad runtime refactor is not a prerequisite for useful initial drift checks.

For Compose, inspect configuration after optional-service assembly, sysroot filtering, custom-mount rewriting, and host-path translation. For microVMs, use their actual export/mount plans, not the unused Compose agent object. Do not infer post-entrypoint process identities or final host modes solely from Compose.

Three complementary checks

1. Deterministic generated-document check: resolve representative configurations with synthetic paths/UIDs, render a clearly marked section of the single document, and fail CI when regeneration differs. Provide an explicit update command. Normalize unstable values without concealing meaningful differences. Never generate from live secret-bearing configuration or publish credentials, private tokens, or actual user-specific paths.
2. Independent contract assertions: assert security and correctness properties against the final plans. Examples include no agent exposure of enclave-private roots, no upgrade of pre-existing read-only mounts through allowWrite, preservation of required credential masks, and expected consumers/access modes for shared channels. Regenerating the document must not be sufficient to approve a contract violation.
3. Runtime conformance checks: on appropriate Linux runners, inspect live mounts, final IDs/groups, ownership/modes, and relevant confinement; attempt allowed and denied operations as the final workload identity, not a privileged diagnostic process. Check both directions of shared channels where relevant. Keep runtime-specific evidence explicit; configuration snapshots alone do not prove enforcement.

Challenging corner cases

• Nested mounts and shadowing: broad read-only parents with writable children; later overlays replacing earlier content; mountpoint creation inside a read-only parent; credential masks at both direct and chroot-prefixed destinations.
• Aliases and path resolution: symlinks, missing descendants, bind aliases, hard links, duplicate sources at different destinations, and overlapping exports. A denied path must not remain reachable through another exposed alias.
• Identity transitions: root initialization followed by privilege drop, invoking-user remapping, UID/GID collisions, supplementary groups, image-defined users, and host/container ID mappings. Startup write success does not prove workload write success.
• Permission lifecycle: umask, pre-existing files/directories, differing service owners, setgid/sticky bits, default ACLs, and entrypoint mutations. Distinguish a world-writable log parent from more restrictive payload-bearing files; do not extrapolate directory modes to every child.
• Conditional mounts: absent home/tool paths, Gemini gating, custom working directories, custom binds with omitted modes, Docker sockets, optional CAs, and feature-specific routing inputs/outputs.
• ARC/DinD split filesystems: runner versus daemon path interpretation, prefix translation, kernel VFS passthrough, sysroot replacement/filtering, and shared versus unshared temporary directories.
• Backend differences: Compose binds, sbx sharing/credential move-aside behavior, Cloud Hypervisor host mount trees and virtio-fs exports, and NVX policy enforcement. Mark rejected combinations and fallback behavior explicitly.
• Private transport and enclave isolation: private roots outside broad agent-visible paths, control/capability files, dedicated broker/executor shares, and ensuring a new custom mount cannot expose a private root indirectly.
• Temporal changes and cleanup: setup-only access, sources created after planning, credential restoration, preserved artifacts, interrupted runs, and stale directories reused by later runs.
• Mount options versus effective enforcement: nested submounts and propagation, read-only export metadata versus actual host enforcement, and capabilities or socket access that confer authority beyond ordinary file reads/writes.

Acceptance criteria

• One discoverable Filesystem Sharing Contract document defines the model, identity table, access matrix, negative guarantees, and verification limitations.
• All supported runtime families and applicable components are inventoried, with explicit activation conditions and a scenario/coverage matrix; unsupported or unverified cases are labeled.
• Generated inventory comes from final implementation builders/planners, with explicit treatment of identity transitions and permission mutations outside those planners.
• A deterministic generation/update command and CI drift check protect the generated sections; fixtures contain no secrets or personal paths.
• Independent contract assertions prevent accepting unsafe behavior merely by refreshing generated output.
• Targeted runtime conformance checks verify representative permitted and denied operations under actual workload identities; broader coverage gaps are documented.
• Existing related documentation links to the contract and contradictory mount examples are reconciled.
• Contributors have clear instructions for updating implementation, generated tables, assertions, and scenario coverage together when filesystem sharing changes.

Suggested delivery sequence

1. Inventory final sharing plans and identity/permission setup; write document semantics and declare scenario coverage.
2. Generate initial access tables from existing builders/planners and add the deterministic drift check plus focused contract assertions.
3. Add targeted live conformance coverage using existing runner/test infrastructure.
4. Incrementally consolidate mount, identity, and permission setup into a typed shared plan to remove remaining duplication.

Documentation and checks should preserve existing intended behavior; any proposed access-policy change should be reviewed separately and explicitly.