Document the trust model and the outer-clamp design

[Gudge (MGudgin)]

• I have signed the Contributor License Agreement.
• This pull request is related to an issue.
• If this PR changes build commands, project architecture, or key conventions, I have updated .github/copilot-instructions.md.

---

Summary

This PR documents MXC's authorization model and the platform-dependent external bounds that can constrain it. It is documentation only: genuinely unbypassable clamps require OS or host infrastructure outside this repository, so the document states the current guarantees and gaps without implying an in-repo enforcement boundary that does not exist.

Details

• Describe the one-principal model and its precondition: the invoker and config author must be the same trust principal; embedders accepting lower-trust config input must impose their own constraints.
• Distinguish secure defaults, buffered relaxation diagnostics, and targeted catastrophic-capability rejection from a general authority ceiling. Diagnostic entries are visible with --debug, a configured sink, or relevant error paths, but not after a successful default non-debug CLI run.
• Classify the Windows execution tiers as enforcing the caller-authored policy rather than supplying an independent clamp. BFS is absent from stock builds; DACL mutation is the default fallback unless fallback.allowDaclMutation=false.
• Record the Hyperlight and NanVix blockedHosts audit/enforcement gaps and the corresponding follow-up issues.
• Survey the external Windows broker, Linux LSM/root policy, macOS SIP/root policy, and a possible in-repo clamp-policy file, clearly separating OS guarantees from deferred repository work.

Tests

• git diff --check

Related Issues

• Hyperlight blockedHosts overrides defaultPolicy=block #786
• NanVix blockedHosts overrides defaultPolicy=block #787

Stack

Merge bottom-up; this document depends on the mechanisms introduced by the earlier PRs.

1. Log boundary relaxations with secure-default warnings #726 — boundary-relaxation diagnostics
2. Make seatbelt.profileOverride dev-only (rejected by shipped builds) #727 — reject seatbelt.profileOverride in shipped builds
3. This PR — document the trust model and outer-clamp design

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Pull request overview

Documents MXC’s trust assumptions and proposed platform-specific outer-clamp model.

Changes:

• Defines the single-principal authorization model.
• Documents secure defaults, relaxation logging, and release-build safeguards.
• Compares potential clamp mechanisms across platforms.

Show a summary per file

File	Description
docs/versioning.md	Adds the trust model and outer-clamp design.

Review details

Tip

Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

• Files reviewed: 1/1 changed files
• Comments generated: 3
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (4)

docs/versioning.md:504

• This describes the pre-#726 logging path. The current #726 head routes relaxation records through Logger::warning_line, which always writes to stderr, including successful default non-debug CLI runs. Leaving this limitation here would make the document stale as soon as the load-bearing stack is merged; the remaining gap is structured propagation through the in-process SDK.

   configuration and infrastructure error paths. A successful default non-debug
   run does not currently print the buffer, so this audit is not yet loud or
   externally auditable in that mode. Filesystem path grants and the Seatbelt

docs/versioning.md:531

• This table now correctly says the Windows broker is not an independent clamp and that DACL mutation is enabled by default unless explicitly disabled (FallbackPolicy::default() sets it to true). The PR description still calls the broker row unbypassable and says DACL requires explicit opt-in, so the review/merge record contradicts both the document and implementation. Update the PR description to match these corrected rows.

| Windows — BaseContainer tier | None separate: the OS broker enforces the caller-authored sandbox spec | No independent ceiling | Current behavior; a fully relaxed config is passed to `Experimental_CreateProcessInSandbox` |
| Windows — AppContainer fallback tiers (BFS / DACL) | None separate: AppContainer, BFS, and DACL ACEs enforce the caller-authored paths | No independent ceiling | Current behavior; BFS is absent from a stock build and requires the non-default `tier2_bfs` feature plus `bfscfg.exe`, while DACL is the default stock fallback unless `fallback.allowDaclMutation=false` |

docs/versioning.md:535

• The “Unbypassable?” column applies inconsistent adversaries: the cross-platform file is marked bypassable because a local admin can edit it, while the LXC row is marked unbypassable even though host root can normally reconfigure its LSM/root-owned policy; SIP can likewise be disabled by a device owner with recovery access. Define whether host administrators are in scope, then classify every row consistently (for example, kernel-enforced against the sandboxed workload versus resistant to host-administrator changes).

| Linux (LXC) | Host LSM (AppArmor / SELinux) profile + root-owned policy file | Yes, with a host LSM; otherwise advisory | OS-infra / host config |
| Linux (Bubblewrap) | LSM, or compile-time capability removal | Partial — bwrap is unprivileged by design | OS-infra / build |
| macOS (Seatbelt) | Root-owned policy file + codesign / SIP | Yes, with SIP + signed binary; otherwise advisory | OS-infra (outside this repo) |
| All platforms | Root/admin-owned **clamp-policy file** read at the trust boundary, capping the boundary relaxations the parser accepts | No — a trust-boundary gate, bypassable by a local admin, not a kernel guarantee | Deferred (in-repo candidate) |

docs/versioning.md:510

• The current #726 head explicitly detects and warns when blockedHosts widens networking on Hyperlight, NanVix, or applicable Bubblewrap configurations. The backend bugs tracked by #786/#787 remain, but the claim that the generic audit omits them will be false after this stack is merged.

   `network.blockedHosts`: Hyperlight and NanVix currently interpret a non-empty
   blocklist as allow-all-except even when `network.defaultPolicy=block`, while
   the generic audit assumes blocklists only subtract connectivity and does not
   log them. The backend fixes are tracked in

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (4)

docs/versioning.md:502

• This describes the pre-#726 buffering behavior, but the current implementation emits every relaxation through Logger::warning_line, which unconditionally writes to stderr even in Mode::Buffer (src/core/wxc_common/src/logger.rs:256-260). Successful default non-debug CLI runs therefore do expose these warnings; documenting them as silent contradicts both the implementation and this PR's dependency.

   `SECURITY: boundary relaxed: …`. They are immediately visible with `--debug`
   or a configured diagnostic log sink, and the default CLIs print the buffer on
   configuration and infrastructure error paths. A successful default non-debug
   run does not currently print the buffer, so this audit is not yet loud or
   externally auditable in that mode. Filesystem path grants and the Seatbelt

docs/versioning.md:534

• This marks the macOS design unbypassable without naming an OS primitive that protects either the arbitrary policy file or the third-party executable. SIP only clamps protected system paths (as documented in docs/macos-support/seatbelt-backend.md:438-440), while code signing alone does not force callers to use that binary or prevent an administrator from replacing the policy/binary. That is the same bypass used to classify the all-platform policy-file row as non-kernel-enforced, so this row currently overstates the guarantee.

| macOS (Seatbelt) | Root-owned policy file + codesign / SIP | Yes, with SIP + signed binary; otherwise advisory | OS-infra (outside this repo) |

docs/versioning.md:508

• The generic audit no longer has this gap. log_boundary_relaxations explicitly detects blockedHosts with defaultPolicy=block for Hyperlight and MicroVM and emits a warning (src/core/wxc_common/src/config_parser.rs:844-879), with regression coverage at lines 2160-2175. The backend enforcement bugs remain, but the claim that they are not logged is now inaccurate.

   primary purpose rather than a relaxation. One known gap is
   `network.blockedHosts`: Hyperlight and NanVix currently interpret a non-empty
   blocklist as allow-all-except even when `network.defaultPolicy=block`, while
   the generic audit assumes blocklists only subtract connectivity and does not
   log them. The backend fixes are tracked in

docs/versioning.md:473

• This introductory sentence is a fragment because the subject has no main verb.

MXC's authorization model and the platform-dependent external bounds that can
constrain what a config relaxes.

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Balanced