Skip to content
Merged
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
39 changes: 33 additions & 6 deletions .github/workflows/macos.yml
Original file line number Diff line number Diff line change
@@ -1,11 +1,14 @@
name: macOS

# Builds the macOS app bundle for each architecture, signs it ad hoc with the
# release's hardened runtime and entitlements, packs it into a disk image, and
# checks the app in the image launches and lists devices. Pull requests that
# change the packaging run it; nightly runs it against main. release.yml calls
# it with `sign`, which signs and notarizes the app as the Developer ID, then
# the disk image holding it, checks them again, and ships the images.
# Builds the macOS app bundle for each architecture, with CEF for browser
# sources, signs it ad hoc with the release's hardened runtime and
# entitlements, runs the browser-source tests against it on Apple silicon,
# packs it into a disk image, and checks the app in the image launches and
# lists devices. Pull requests that change the packaging run it; nightly runs
# it against main.
# release.yml calls it with `sign`, which signs and notarizes the app as the
# Developer ID, then the disk image holding it, checks them again, and ships
# the images.

permissions:
contents: read
Expand Down Expand Up @@ -55,6 +58,13 @@ jobs:
persist-credentials: false
submodules: true

# cef-dll-sys builds CEF's C++ wrapper with CMake, which the image has,
# and Ninja, which it may lack.
- name: Install Ninja
env:
HOMEBREW_NO_AUTO_UPDATE: "1"
run: command -v ninja || brew install ninja

# The image's rustup installs the toolchain rust-toolchain.toml names, and
# Xcode's own linker and SDK keep the binary free of Nix store paths.
- name: Build
Expand All @@ -63,6 +73,23 @@ jobs:
- name: Sign ad hoc
run: packaging/macos/sign.sh "kixel.live Studio.app" -

# Browser sources against the signed bundle, the only place CEF runs
# from on macOS: drawn on the GPU, played, clicked, typed into, copied,
# kept logged in, and crashing alone. One at a time, since a test finds
# its helper among the processes this one started. The harness builds in
# the dev profile: only the bundle it drives needs release, and a second
# fat-LTO build of the studio would add an hour. Apple silicon only: the
# Intel runners' paravirtual GPU passes for Metal to the studio, but
# Chromium's GPU process cannot start ANGLE on it and the browser exits.
- name: Browser sources
if: matrix.arch == 'arm64'
env:
MOQ_STUDIO_APP: ${{ github.workspace }}/kixel.live Studio.app
MACOSX_DEPLOYMENT_TARGET: "13.0"
run: >-
cargo test --locked -p moq-studio --features cef --test browser --
--include-ignored --test-threads=1

# dmg.sh's builder needs a newer Python than macOS ships.
- name: Set up Python
uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
Expand Down
6 changes: 6 additions & 0 deletions Cargo.lock

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

36 changes: 21 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,9 +73,12 @@ cargo run --release -p moq-studio --features capture,openh264
encoder.
- `release` is what the packages build: `capture`, `openh264`, and the
hardware codecs. The Flatpak adds `pipewire`.
- `cef` adds browser sources, on Linux only for now. The build takes CEF from
`CEF_PATH`, which the dev shell sets, or else downloads it, and the binary
loads `libcef.so` from beside itself or from that `CEF_PATH`.
- `cef` adds browser sources, on Linux and macOS. The build takes CEF from
`CEF_PATH`, which the dev shell sets on Linux, or else downloads it. On
Linux the binary loads `libcef.so` from beside itself or from that
`CEF_PATH`. On macOS browser sources run only from the app bundle, which
holds CEF's framework and its helper apps: build it with
`packaging/macos/bundle.sh`, which the macOS packages ship with `cef`.
- On Linux, display and window sources capture X11 and XWayland by id. With
`pipewire`, a display or window can also be picked in the desktop's
screen-sharing picker, the only way to share a Wayland screen; see
Expand Down Expand Up @@ -914,17 +917,19 @@ A browser source renders a web page, such as an overlay, alert box, or chat
widget, at the canvas frame rate (CEF caps it at 60) over a transparent
background, and its sound joins the audio scenes that hold it. Every page shares one
browser profile, kept in `$XDG_DATA_HOME/moq-studio/browser`
(`~/.local/share/moq-studio/browser` by default) rather than beside the scene
file, so cookies and logins, such as an alert service's, survive a reload and
a restart of the studio. They are not encrypted with the desktop's keyring,
so a locked keyring never holds a page back, and anything that can read your
home directory can read them. One studio at a time can use the profile: a
(`~/.local/share/moq-studio/browser` by default) on Linux and in
`~/Library/Application Support/moq-studio/browser` on macOS, rather than
beside the scene file, so cookies and logins, such as an alert service's,
survive a reload and a restart of the studio. They are not encrypted with the
desktop's keyring or keychain, so a locked keyring never holds a page back and
no keychain prompt interrupts one, and anything that can read your home
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. On Linux,
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. 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.
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 @@ -933,9 +938,9 @@ browser extensions, even ones your distribution installs for every Chromium.
lists, such as a `<select>`'s, draw over it and take clicks under
**Interact**, but it opens no other windows (`window.open` and new-tab links
do nothing). Copy and Cut there put the page's selected text on the clipboard,
and nothing from a password field. 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.
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.

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))
Expand Down Expand Up @@ -1738,7 +1743,8 @@ paints, given the same Vulkan DMA-BUF import and a display to paint through:
the Wayland one when `$WAYLAND_DISPLAY` is set and has an output, such as a
monitor, needing no XWayland, or else
the X one in `$DISPLAY`, when the X server runs on the studio's GPU, since
CEF paints on the X server's there. Every other source, every source on Windows or on a
CEF paints on the X server's there. On macOS it is copied from the IOSurface
CEF paints, through Metal. Every other source, every source on Windows or on a
GPU that cannot import, and every still image delivers its frames from the
CPU, which the compositor uploads. A browser source takes that path with no
display at all too, and there renders its page in software, WebGL included, so
Expand Down
29 changes: 29 additions & 0 deletions packaging/macos/Helper.plist
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<!-- Each helper app CEF starts its subprocesses from. bundle.sh writes the
name, identifier, and moq-studio's version. -->
<dict>
<key>CFBundleDevelopmentRegion</key>
<string>en</string>
<key>CFBundleExecutable</key>
<string>moq-studio Helper</string>
<key>CFBundleIdentifier</key>
<string>live.kixel.studio.helper</string>
<key>CFBundleInfoDictionaryVersion</key>
<string>6.0</string>
<key>CFBundleName</key>
<string>moq-studio Helper</string>
<key>CFBundlePackageType</key>
<string>APPL</string>
<key>CFBundleShortVersionString</key>
<string>0.0.0</string>
<key>CFBundleVersion</key>
<string>0.0.0</string>
<key>LSMinimumSystemVersion</key>
<string>13.0</string>
<!-- No Dock icon or menu bar: the studio's stands for it. -->
<key>LSUIElement</key>
<true/>
</dict>
</plist>
52 changes: 44 additions & 8 deletions packaging/macos/bundle.sh
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
#!/usr/bin/env bash
# Build moq-studio with the `release` feature for this Mac's architecture and
# lay it out as an app bundle at the path given, unsigned; sign.sh signs it.
# Needs Xcode's command line tools, cargo, and jq.
# Build moq-studio with the `release` and `cef` features for this Mac's
# architecture and lay it out as an app bundle at the path given, unsigned;
# sign.sh signs it. Needs Xcode's command line tools, cargo, CMake, Ninja,
# and jq.
set -euo pipefail

app=$1
Expand All @@ -11,23 +12,58 @@ cd "$packaging/../.."
# Info.plist's LSMinimumSystemVersion, so the linker and OpenH264's C build
# target the oldest macOS the bundle claims.
export MACOSX_DEPLOYMENT_TARGET=13.0
json=$(cargo build --locked --release -p moq-studio --features release --message-format=json-render-diagnostics)
# The binary, and the build script's output, which holds the icon it drew.
executable=$(jq -r 'select(.reason == "compiler-artifact" and .target.name == "moq-studio" and .executable != null) | .executable' <<<"$json")
# The studio, and the binary CEF's subprocesses run from (browser sources).
json=$(cargo build --locked --release -p moq-studio -p moq-scene --bin moq-studio --bin moq-browser-helper \
--features moq-studio/release,moq-studio/cef,moq-scene/cef --message-format=json-render-diagnostics)
# The binaries, the build script's output, which holds the icon it drew, and
# cef-dll-sys's, where it downloads CEF unless CEF_PATH names a copy.
artifact() {
jq -r --arg name "$1" 'select(.reason == "compiler-artifact" and .target.name == $name and .executable != null) | .executable' <<<"$json"
}
executable=$(artifact moq-studio)
helper=$(artifact moq-browser-helper)
out=$(jq -r 'select(.reason == "build-script-executed" and (.package_id | test("/rs/moq-studio#"))) | .out_dir' <<<"$json")
cef=$(jq -r 'select(.reason == "build-script-executed" and (.package_id | test("cef-dll-sys"))) | .out_dir' <<<"$json")
version=$(cargo metadata --locked --no-deps --format-version 1 | jq -r '.packages[] | select(.name == "moq-studio") | .version')
[[ -x $executable && -f $out/live.kixel.studio.icns && -n $version ]]
[[ -x $executable && -x $helper && -f $out/live.kixel.studio.icns && -n $version ]]
frameworks=()
while IFS= read -r framework; do
frameworks+=("$framework")
done < <(find "${CEF_PATH:-$cef}" -maxdepth 3 -type d -name "Chromium Embedded Framework.framework")
((${#frameworks[@]} == 1))

# Nested code, such as helpers, frameworks, and system extensions, goes under
# Contents in the directory macOS expects it in, and sign.sh signs it first.
rm -rf "$app"
# Readable by every user, whatever this checkout's own modes.
umask 022
mkdir -p "$app/Contents/MacOS" "$app/Contents/Resources"
mkdir -p "$app/Contents/MacOS" "$app/Contents/Resources" "$app/Contents/Frameworks"
cp "$packaging/Info.plist" "$app/Contents/Info.plist"
chmod 644 "$app/Contents/Info.plist"
plutil -replace CFBundleShortVersionString -string "$version" "$app/Contents/Info.plist"
plutil -replace CFBundleVersion -string "$version" "$app/Contents/Info.plist"
plutil -lint "$app/Contents/Info.plist"
cp "$executable" "$app/Contents/MacOS/moq-studio"
cp "$out/live.kixel.studio.icns" "$app/Contents/Resources/live.kixel.studio.icns"

# CEF, which the studio's executable loads when it starts again as the
# browser-source helper, and the helper apps CEF starts its subprocesses
# from: `<executable> Helper.app` and its variants, each named and identified
# as CEF looks for them.
ditto "${frameworks[0]}" "$app/Contents/Frameworks/Chromium Embedded Framework.framework"
for variant in "" " (GPU)" " (Renderer)" " (Plugin)" " (Alerts)"; do
name="moq-studio Helper$variant"
contents="$app/Contents/Frameworks/$name.app/Contents"
mkdir -p "$contents/MacOS"
cp "$packaging/Helper.plist" "$contents/Info.plist"
chmod 644 "$contents/Info.plist"
# `(GPU)` names `live.kixel.studio.helper.gpu`.
suffix=$(tr -d ' ()' <<<"$variant" | tr '[:upper:]' '[:lower:]')
plutil -replace CFBundleExecutable -string "$name" "$contents/Info.plist"
plutil -replace CFBundleIdentifier -string "live.kixel.studio.helper${suffix:+.$suffix}" "$contents/Info.plist"
plutil -replace CFBundleName -string "$name" "$contents/Info.plist"
plutil -replace CFBundleShortVersionString -string "$version" "$contents/Info.plist"
plutil -replace CFBundleVersion -string "$version" "$contents/Info.plist"
plutil -lint "$contents/Info.plist"
cp "$helper" "$contents/MacOS/$name"
done
10 changes: 10 additions & 0 deletions packaging/macos/jit.entitlements.plist
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<!-- CEF's plain, renderer, and GPU helpers, which compile JavaScript,
WebAssembly, and SwiftShader's shaders at run time, as Chrome's do. -->
<dict>
<key>com.apple.security.cs.allow-jit</key>
<true/>
</dict>
</plist>
30 changes: 29 additions & 1 deletion packaging/macos/sign.sh
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,35 @@ if [[ -n $keychain ]]; then
flags+=(--keychain "$keychain")
fi

# The entitlements each helper app's process needs, by its name: none but
# those that compile code at run time: the GPU and renderer helpers, and the
# plain one too, since CEF 156 starts pages' renderers and utility processes
# from it, and under the hardened runtime V8 cannot reserve its code range
# without `allow-jit`.
entitlements() {
case $1 in
*" Helper.app" | *" Helper (Renderer).app" | *" Helper (GPU).app") echo "$packaging/jit.entitlements.plist" ;;
*.app) ;;
*)
echo "no entitlements known for $1" >&2
return 1
;;
esac
}

# Nested code is signed before the bundle that holds it, innermost first, each
# with its own entitlements; the bundle's signature then seals theirs.
# with its own entitlements; the bundle's signature then seals theirs. A
# framework's libraries go before the framework.
shopt -s nullglob
for framework in "$app"/Contents/Frameworks/*.framework; do
for library in "$framework"/Libraries/*.dylib; do
codesign "${flags[@]}" "$library"
done
codesign "${flags[@]}" "$framework"
done
for helper in "$app"/Contents/Frameworks/*.app; do
plist=$(entitlements "$helper")
codesign "${flags[@]}" ${plist:+--entitlements "$plist"} "$helper"
done
codesign "${flags[@]}" --entitlements "$packaging/entitlements.plist" "$app"
codesign --verify --strict --deep --verbose=2 "$app"
7 changes: 7 additions & 0 deletions quest/m0/browser-source/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,13 @@ The studio holds the channel open until the helper exits and stops it with
starts, as the studio dying, and kills the process group it leads with CEF's
processes. Each platform's quest says what it needs on top.

macOS landed next: the helper is still the studio's executable started
again, and CEF's subprocesses run from `moq-studio Helper.app` and its
variants beside CEF's framework under `Contents/Frameworks`, so browser
sources run only from the app bundle.
Each picture's IOSurface crosses as a Mach port, sent to a bootstrap service
the studio checks in per helper, and taken only from the helper's pid.

Decided 2026-11-09 (maintainer, /quest-audit): ✅ one quest per platform
(rejected: Related links only; leaving one quest). One quest held macOS
behind the Windows host, and shaped the macOS app bundle with no link to the
Expand Down
23 changes: 0 additions & 23 deletions quest/m0/browser-source/macos.md

This file was deleted.

33 changes: 33 additions & 0 deletions quest/m1/browser-sandbox.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# [L] Chromium's sandbox for browser sources

## 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
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
4 changes: 2 additions & 2 deletions quest/m1/panels.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,8 @@ page is the platform's own.
- A page can do anything the browser can, as a browser source can: the same
warning to add only pages you trust applies, and is shown when adding one.

Browser sources exist on Linux only today, so panels arrive on macOS and
Windows with them.
Browser sources exist on Linux and macOS today, so panels arrive on Windows
with them.

Human check: a real chat page, logged in, typed into during a stream.

Expand Down
Loading
Loading