Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions .github/workflows/nightly.yml
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,22 @@ jobs:

- uses: ./.github/actions/nix

# Ubuntu's AppArmor lets a program make the user namespaces Chromium's
# sandbox needs only where a profile allows it, and browser sources
# fail without them: the README's profile, for the studio the browser
# tests run.
- name: Allow the studio user namespaces
run: |
sudo tee /etc/apparmor.d/moq-studio >/dev/null <<EOF
abi <abi/4.0>,
include <tunables/global>

profile moq-studio $GITHUB_WORKSPACE/target/debug/moq-studio flags=(unconfined) {
userns,
}
EOF
sudo apparmor_parser -r /etc/apparmor.d/moq-studio

- name: Render
run: nix develop --command just render-sw

Expand Down
1 change: 1 addition & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

24 changes: 21 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -937,9 +937,9 @@ directory can read them. One studio at a time can use the profile: a
second one's browser sources fail saying so. Each page renders in a process of its own, so
a page that crashes fails only its own source, with the reason, while the
stream carries on. A crash of the browser itself fails every browser source.
Either shows at once, since the browser's processes dump no core. Pages run
without Chromium's sandbox, as in OBS, so a page that exploits a browser bug
can do anything you can: add only pages you trust.
Either shows at once, since the browser's processes dump no core. Each page
renders in Chromium's sandbox, so a page that exploits a browser bug still
cannot read your files, keys, or stream credentials.
The browser requests only what its pages load, never asking Google for
updates, the time, or autofill suggestions on its own, so pages are not
spellchecked, which would need a dictionary from Google. Nor does it run
Expand All @@ -952,6 +952,24 @@ and nothing from a password field. On Linux, except for a page copied on the
GPU through an X display, the text goes as plain text that the page's own copy
handlers cannot change; on macOS the page copies as it would in a browser.

On Linux the sandbox needs unprivileged user namespaces, and a studio run by
a user other than root. Where either is missing, browser sources fail saying
so rather than render a page unsandboxed. Ubuntu refuses them, since
23.10, to any program an AppArmor profile does not allow; as root, allow the
studio, naming the `moq-studio` you run:

```bash
cat >/etc/apparmor.d/moq-studio <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile moq-studio /path/to/moq-studio flags=(unconfined) {
userns,
}
EOF
apparmor_parser -r /etc/apparmor.d/moq-studio
```

An overlay is a title, lower third, or other graphic written as HTML and CSS,
drawn by the studio itself (through [Blitz](https://github.com/DioxusLabs/blitz))
rather than a browser, on every platform. Its CSS animations and transitions
Expand Down
29 changes: 29 additions & 0 deletions quest/m0/nightly-macos-check.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# [S] Nightly macOS check passes again

## Goal

The nightly workflow's macOS job, `just ci` on `macos-latest`, passes on
`main`, as it did on 2026-11-18.

## Plan

It has failed since 2026-11-19
([run 44766089244](https://github.com/moq-dev/studio/actions/runs/44766089244))
with two compile errors no Linux check sees:

- `rs/moq-scene/src/browser/mach.rs:289`, a test: no method `id` on
`CFRetained<IOSurfaceRef>`. Likely a feature of `objc2-io-surface`
(`IOSurfaceTypes`, which holds `IOSurfaceID`) that something else in the
graph used to turn on; find what changed in `Cargo.lock` between the two
runs and name the feature in `rs/moq-scene/Cargo.toml`.
- `rs/moq-studio/src/controls.rs`: `Fixed::id` and `Action::id` are dead code
on macOS, under `-D warnings`. Give them their macOS consumer, or gate them
on the platforms that read them.

Fix on a Mac or by pushing and reading the nightly run
(`gh workflow run nightly.yml --ref <branch>`); a pull request runs no macOS
`just ci`.

## Hosts

- macos - the errors compile only there
30 changes: 30 additions & 0 deletions quest/m1/browser-sandbox-mac-check.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# [XS] Check sandboxed browser sources in the signed macOS app

## Goal

The maintainer has run a browser source in the Developer ID signed,
notarized macOS app, installed from its disk image, and seen its page draw
with its renderer sandboxed, or the fix it needs is written into this Plan.

## Plan

[moq-dev/studio#223](https://github.com/moq-dev/studio/pull/223) sandboxes
each page's renderer on macOS. `macos.yml` runs the browser-source tests,
`a_renderer_cannot_read_the_user_s_files` among them, against an ad hoc
signed bundle with the release's hardened runtime and entitlements, but not
against the release's own signature, notarization, and quarantine, which a
download runs under (App Translocation moves a quarantined app to a random
read-only path, from which Chromium builds its sandbox's rules).

## Waiting

- Maintainer: on a Mac, download the next release's disk image (or a
`release.yml` run's `macos-arm64` artifact) in a browser, open the app
once from the image and once from Applications, add a browser source such
as `https://webglsamples.org/aquarium/aquarium.html`, and check that it
draws and plays, and that Activity Monitor's Sandbox column (View, Columns)
says Yes for `moq-studio Helper (Renderer)` and `moq-studio Helper (GPU)`.
No reachable Mac runs a signed app, and the release job runs nothing built
until its signing credentials leave the runner; running the browser tests
there was considered and would add a second hour-long build of the test
harness to every release. Check: a comment or this Plan records the result.
54 changes: 28 additions & 26 deletions quest/m1/browser-sandbox.md
Original file line number Diff line number Diff line change
@@ -1,33 +1,35 @@
# [L] Chromium's sandbox for browser sources
# [M] Chromium's sandbox for browser sources on Windows

## Goal

A browser source's renderer runs inside Chromium's sandbox on every
platform browser sources run on, so a hostile page, or an overlay site that
gets compromised, cannot read the creator's files, keys, or stream credentials
A browser source's renderer on Windows runs inside Chromium's sandbox, as it
does on Linux and macOS, so a hostile page, or an overlay site that gets
compromised, cannot read the creator's files, keys, or stream credentials
through a renderer exploit. The helper passes no `--no-sandbox`.

## Plan

Today every platform starts CEF with `--no-sandbox`
(`rs/moq-scene/src/browser/host.rs`), and the README warns to add only pages
you trust.

- **Linux:** Chromium's namespace sandbox needs unprivileged user namespaces,
which some distributions restrict (Ubuntu's AppArmor rule since 24.04);
the setuid `chrome-sandbox` fallback needs root to install. Recommendation:
use the namespace sandbox, and when the kernel refuses it, fail the browser
source loudly with what to enable rather than run unsandboxed.
- **macOS:** link CEF's `cef_sandbox` static library into
`moq-browser-helper` and enter the Seatbelt sandbox first thing in its
`main`, as CEF's sample helpers do. Check the renderer's and GPU helper's
entitlements in `packaging/macos/sign.sh` still suffice.
- **Windows:** CEF's sandbox needs its `cef_sandbox.lib` linked into the
executable and `bootstrap.exe`'s layout; land with or after
[Browser sources on Windows](/quest/m0/browser-source/windows.md).
- A test per platform proves a page's renderer cannot open a file outside its
profile.

## Related

- [Browser sources on macOS and Windows](/quest/m0/browser-source/README.md) - the browser sources this sandboxes
Linux and macOS landed in
[moq-dev/studio#223](https://github.com/moq-dev/studio/pull/223): on Linux
`moq_scene::browser::sandbox::check` refuses to start CEF where the kernel
refuses the user namespaces Chromium needs, and on macOS each helper app
enters the Seatbelt sandbox through CEF's `libcef_sandbox.dylib`
(`cef::sandbox::Sandbox`) before it loads CEF's framework.

- CEF's Windows sandbox needs `cef_sandbox.lib` linked into the executable
that runs the subprocesses, with its sandbox info passed to
`execute_process` and `initialize`, and `bootstrap.exe`'s layout. The `cef`
crate's `sandbox` feature, which `moq-scene` leaves off with its other
defaults, builds CEF's wrapper with it.
- Prove it the way `a_renderer_cannot_read_the_user_s_files` in
`rs/moq-studio/tests/browser.rs` does on Linux and macOS: a Windows
`can_read` that asks whether the renderer's restricted, untrusted-integrity
token may open a file the test wrote, where the helper's may.

## Hosts

- windows - CEF's Windows sandbox

## Required

- [Browser sources on Windows](/quest/m0/browser-source/windows.md) - browser sources run on Windows at all
6 changes: 5 additions & 1 deletion rs/moq-scene/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ pipewire = ["capture", "moq-video/pipewire", "moq-audio/pipewire"]
# process, on Linux and macOS. Off by default: the build downloads the CEF
# runtime, or takes it from `CEF_PATH`, and compiles its C++ wrapper. Without
# it, a browser source reports that this build cannot render web pages.
cef = ["dep:cef", "dep:objc2", "dep:objc2-app-kit", "dep:objc2-foundation"]
cef = ["dep:cef", "dep:libc", "dep:objc2", "dep:objc2-app-kit", "dep:objc2-foundation"]

# CEF's subprocesses on macOS, which run from helper apps of their own in the
# app bundle rather than from the studio's executable.
Expand Down Expand Up @@ -111,6 +111,10 @@ x11rb = { version = "0.13", features = ["dri3"] }
# Whether the Wayland display has an output, without which CEF's `initialize`
# hangs. Pure Rust, and 0.31 as eframe's winit uses.
wayland-client = "0.31"
# Forks a child that makes the user namespaces Chromium's sandbox needs, which
# rustix leaves out, since the child of a threaded process may make only raw
# system calls. Already in the graph.
libc = { version = "0.2", optional = true }

# Each is the release already in the graph through wgpu and winit.
[target.'cfg(target_os = "macos")'.dependencies]
Expand Down
24 changes: 16 additions & 8 deletions rs/moq-scene/src/browser/host.rs
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,17 @@ const COPIED: &str = "moq-studio-copied";

/// Run one of CEF's subprocesses (renderer, GPU, utility, zygote).
pub(super) fn subprocess() -> ExitCode {
let args = args::Args::new();
// On macOS each subprocess enters Chromium's sandbox for its kind itself,
// before CEF's framework loads, as CEF's own helpers do, and leaves it
// only as it exits. Every bundle holds the sandbox's library, so a helper
// that cannot load it panics. On Linux the zygote CEF starts does this.
#[cfg(target_os = "macos")]
let _sandbox = {
let mut sandbox = cef::sandbox::Sandbox::new();
sandbox.initialize(args.as_main_args());
sandbox
};
#[cfg(target_os = "macos")]
let _framework = match mac::framework(true) {
Ok(framework) => framework,
Expand All @@ -36,7 +47,6 @@ pub(super) fn subprocess() -> ExitCode {
}
};
let _ = api_hash(sys::CEF_API_VERSION_LAST, 0);
let args = args::Args::new();
let mut app = RendererApp::new(RendererCopy::new());
let code = execute_process(Some(args.as_main_args()), Some(&mut app), std::ptr::null_mut());
ExitCode::from(code.clamp(0, 255) as u8)
Expand Down Expand Up @@ -171,6 +181,11 @@ fn browse(shared: &Arc<Shared>, start: Start, reader: Channel, painted_tx: mpsc:
)
.map_err(|err| format!("cannot turn off core dumps: {err}"))?;

// Chromium sandboxes every page's renderer, and would abort, not run it
// unsandboxed, where it cannot.
#[cfg(target_os = "linux")]
super::sandbox::check()?;

// Read before CEF starts, which can block for good, as on a display that
// never answers, so the studio's end is heard even then.
let inbox = Arc::new(Inbox {
Expand Down Expand Up @@ -613,13 +628,6 @@ wrap_app! {
command_line.append_switch_with_value(Some(&"password-store".into()), Some(&"basic".into()));
#[cfg(target_os = "macos")]
command_line.append_switch(Some(&"use-mock-keychain".into()));
// Chromium's sandbox needs unprivileged user namespaces, which
// Ubuntu's AppArmor and a Flatpak deny, or a setuid-root helper,
// which a user build lacks. Without either, the browser aborts
// rather than run unsandboxed, so the sandbox is off, as in OBS. On
// macOS it needs CEF's sandbox library linked into every helper,
// which the `cef` crate leaves to the app, so it is off there too.
command_line.append_switch(Some(&"no-sandbox".into()));
// The browser requests only what its pages load. Otherwise it asks
// Google, unprompted, for the network time, for autofill's guesses
// at each form a page shows, and for whether AI Mode is offered.
Expand Down
2 changes: 2 additions & 0 deletions rs/moq-scene/src/browser/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,8 @@ mod host;
mod import;
#[cfg(target_os = "macos")]
mod mach;
#[cfg(all(target_os = "linux", feature = "cef"))]
mod sandbox;

#[cfg(any(target_os = "linux", target_os = "macos"))]
pub(crate) use protocol::Open;
Expand Down
90 changes: 90 additions & 0 deletions rs/moq-scene/src/browser/sandbox.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
//! Whether Chromium can sandbox pages on this Linux system, asked before CEF
//! starts, so a browser source fails saying what to change rather than run a
//! page unsandboxed or leave the browser to abort.

use std::ffi::CStr;
use std::io;

/// Fail unless Chromium's namespace sandbox can start: unless the studio runs
/// as a user the kernel lets make a user namespace and another inside it, as
/// Chromium itself checks. Ubuntu's AppArmor, since 23.10, refuses that to any
/// program no profile allows it. Chromium's other sandbox, the setuid-root
/// `chrome-sandbox`, takes root to install, and the copy CEF leaves beside
/// the binary is not setuid, so the studio does not count on it.
pub(super) fn check() -> Result<(), String> {
// SAFETY: neither can fail.
let (uid, gid) = unsafe { (libc::getuid(), libc::getgid()) };
if uid == 0 {
return Err("Chromium sandboxes no pages for root: run the studio as another user".into());
}
// Formatted before forking: the child of a threaded process must not
// allocate, since another thread may hold the allocator's lock.
let uid_map = format!("{uid} {uid} 1");
let gid_map = format!("{gid} {gid} 1");
// SAFETY: the child makes only async-signal-safe calls and leaves through
// `_exit`, never returning into Rust.
let pid = unsafe { libc::fork() };
if pid == -1 {
return Err(format!(
"cannot check for Chromium's sandbox: {}",
io::Error::last_os_error()
));
}
if pid == 0 {
// SAFETY: as above.
unsafe { libc::_exit(nest(&uid_map, &gid_map)) };
}
let mut status = 0;
// SAFETY: `pid` is this process's child, and `status` outlives the call.
while unsafe { libc::waitpid(pid, &mut status, 0) } == -1 {
let err = io::Error::last_os_error();
if err.kind() != io::ErrorKind::Interrupted {
return Err(format!("cannot check for Chromium's sandbox: {err}"));
}
}
let refused = match libc::WIFEXITED(status).then(|| libc::WEXITSTATUS(status)) {
Some(0) => return Ok(()),
Some(1) => "refuses to make a user namespace",
Some(2) => "refuses to map the studio's user into a user namespace",
Some(3) => "refuses to make a user namespace inside another",
_ => "crashed checking for user namespaces",
};
Err(format!(
"Chromium sandboxes pages in user namespaces, and this system {refused}: allow them, as the README describes for browser sources on Linux"
))
}

/// Make a user namespace mapping the studio's user, and another inside it,
/// in a child about to exit. Returns 0, or the step that failed.
fn nest(uid_map: &str, gid_map: &str) -> i32 {
// SAFETY: plain system calls.
if unsafe { libc::unshare(libc::CLONE_NEWUSER) } != 0 {
return 1;
}
// An unprivileged user maps its group only once it gives up setgroups.
if !write(c"/proc/self/setgroups", b"deny")
|| !write(c"/proc/self/gid_map", gid_map.as_bytes())
|| !write(c"/proc/self/uid_map", uid_map.as_bytes())
{
return 2;
}
// SAFETY: as above.
if unsafe { libc::unshare(libc::CLONE_NEWUSER) } != 0 {
return 3;
}
0
}

/// Write all of `data` to the file at `path`, without allocating.
fn write(path: &CStr, data: &[u8]) -> bool {
// SAFETY: `path` is a C string, and `data` outlives the calls.
unsafe {
let fd = libc::open(path.as_ptr(), libc::O_WRONLY | libc::O_CLOEXEC);
if fd < 0 {
return false;
}
let written = libc::write(fd, data.as_ptr().cast(), data.len());
libc::close(fd);
written == data.len() as isize
}
}
Loading