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
45 changes: 45 additions & 0 deletions bun.lock

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

36 changes: 36 additions & 0 deletions docs/contracts/s15-working-vm-v1.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,42 @@ The external guest network allows only a protected HTTP/CONNECT registry proxy.

**Desktop session (DESK16-01, ADR 0091 decisions 1 and 6).** With `desktop` on, provisioning (and, for a VM enrolled before `desktop` was on, the first desktop beat of a later boot) runs one fixed idempotent guest program through a separate bounded provisioning lease (unfiltered, like the Docker install; always closed afterwards). It creates the unprivileged system user and group `jit-desktop` (no sudo, home `/var/lib/jit-desktop`), downloads the pinned Chrome for Testing archive for the guest architecture (`qemuDesktopBrowser`: version `157.0.8103.50`, one recorded SHA-256 each for x86_64 and arm64) and refuses any other bytes, unpacks it to `/opt/jit-desktop/chrome-<version>`, installs its `deb.deps` plus Xorg (modesetting, 1280×800), libinput, xinit, fluxbox and fonts from Ubuntu's archive, and enables two units: `jit-desktop-proxy.service` (a loopback forwarder on `127.0.0.1:3129` that adds `Proxy-Authorization` from `proxy.env`, read per connection, because Chromium accepts no credentials in a proxy URL) and `jit-desktop.service` (Xorg, fluxbox and the browser on vt7 as `jit-desktop`, browser restarted if it exits, profile in the user's home, sandbox on through an AppArmor `userns` profile for that binary only). The install removes `ready-v1` first and writes it only after both units and the pinned browser have stayed up for three checks in a row, so a partial, failed or outdated install is installed again. A failed install is tried once per boot and leaves the VM working without a desktop lease. A headless controller installs nothing. It is separate from work-session leases: revoking a session never cuts it, and takeover does not touch it. Work-session leases keep the rules above unchanged. Residuals: guest root can read the desktop lease, and any guest process can use the loopback forwarder, so anything in the guest can reach any non-sensitive public host while the VM runs (ADR 0084, ADR 0091); the sensitive-host list is a heuristic.

### Watched desktop CDP stream (ADR 0092, slice 3a)

`vmDesktopCdpStream` is a separate, host-only `BoxStream`, never `invoke`, `control` or the one-shot host runner.
It uses `vmSshArgs` (`ssh -T`, the registered key, port and pinned host key), running exactly
`sudo -n -u jit-desktop /usr/local/lib/jit-desktop/cdp-attach`. The fixed unbuffered Python attach copies bytes
between its pipes and `/run/jit-desktop/cdp.sock`; SSH/sudo stderr is drained separately and never enters CDP.
The controller consumes the first NUL-framed handshake within 10 s: exactly `{"jit":"attached"}` succeeds,
`{"jit":"busy"}` refuses `computer_browser_busy`, and anything else/EOF/timeout closes the stream and refuses
`computer_browser_unavailable`. Bytes following the handshake in the same read are preserved.

The root-owned installed session runs fixed `cdp-relay` as `jit-desktop` with stdin `/dev/null`, instead of running
Chromium directly. The unit first creates `/run/jit-desktop` as `0700 jit-desktop`; the relay verifies that ownership
and mode and binds a `0600` Unix socket. There is no TCP DevTools port. The relay owns Chromium's fd3/fd4
`--remote-debugging-pipe`, sends the handshake before CDP, admits one client, and leaves Chromium and its tabs alive
when that client disconnects. Command ids are remapped across clients so an old reply cannot settle a new call.
A relay exit terminates and reaps its browser; a browser exit ends the relay, allowing the session loop to restart both.
Messages are at most 1 MiB, with bounded queues; stdout never uses Python's buffered file objects.
On disconnect, wholly unsent frames are discarded. A partially sent frame is completed without splicing JSON,
and all sent commands must reply (navigations also receive `Page.stopLoading`, whose reply is awaited) before the relay acknowledges `{"jit":"settled"}` and closes the client socket.
New clients remain busy during this drain. Attach half-closes its Unix socket on stdin EOF, keeps draining replies,
and exits successfully only after that final acknowledgement (or a busy handshake). The host gracefully ends SSH
stdin, continues discarding stdout, and waits for this positive settlement before releasing the screen ticket;
a 15 s drain timeout kills only the SSH process and reports `computer_browser_unsettled`, never proof of guest settlement.
Unproven settlement keeps owner input blocked. The browser process/profile is never killed to cancel a client.

`ready-v1` now holds `<chrome version>+session.<revision>` (currently `cdp-2`) rather than the bare Chrome pin.
The installer, installed check and lease writer share this key. A bare pin upgrades the session, units, relay and attach
without downloading an already unpacked Chrome pin again. The marker is removed first and written only after the
services and socket are ready. Headless provisioning remains unchanged.

The run-scoped controller shares one stream across calls and permits only one controller per VM. It closes on run
end/cancel, 5 minutes idle, screen takeover/generation transitions, VM fencing/stop/restore and service shutdown.
Closing kills SSH/attach, not Chromium. Each tool call has its own 60 s deadline; each CDP command has the existing
15 s deadline. Neither `commandMs` nor `sessionMs` bounds this channel. Missing desktops are refused with
`vm_desktop_unavailable`; stopped VMs are refused before opening. See `s16-computer-browser-v1.md`.

Proxmox setup registers a VM-scoped API token (VM.Audit/PowerMgmt/Snapshot/Snapshot.Rollback), with read-only Sys.Audit at `/` and `/nodes/<node>`. The protected verifier reads all firewall enable levels, NIC/rules and direct guest egress probes. Missing audit or disabled/unproven controls refuses the `network-isolated` capability. Lima/QEMU verifies the actual protected process/config: plain mode, no shared mounts/guest agent/additional NIC, `restrict=on`, IPv6 disabled and only the fixed proxy guest-forward. Guest firewall settings are diagnostic only. Since revision 4 the default x64/arm64 working VM is the Jit-managed local VM below; Lima/Proxmox are the optional owner-supplied path.

The module's separate protected SQLite journal uses application ID `0x4a495456`, version 1. It refuses foreign headers before opening writable SQLite; it is neither the S15 application store nor an S14 migration. SSH keys and VM management tokens stay outside it in protected key files/vault. Native Schway state is unchanged and remains protected. This slice does not activate a complete S15 runtime, implement a new agent loop, adopt legacy data or claim universal browser/effect gates. S14 remains default.
Expand Down
Loading
Loading