desktop, extracted from the platform
x11vnc against display :0 — the session the owner is actually logged into, not a second one Officer installs. sidecar/, api/, web/ and the host setup script, moved out of src/ whole. Dormant when it moved: the websocket was commented out in server.tsx and the router in hono.ts since 2026-08-13, and no officer-vnc process was running on any machine. Nothing regressed and nothing was restored — this took switched-off code out of the platform. The point of the move is what the platform stopped knowing. Its sidecar/protocol.ts carried a VNC section — vnc:start, vnc:ensure-password, vnc:stop, four reply variants, VncStartParams, VncSessionInfo — and sidecar-registry.ts carried startVnc, ensureVncPassword, stopVnc and isVncConnected. That is the platform speaking a plugin's vocabulary, which CLAUDE.md names as a rule and this was the clearest breach of. All of it is in sidecar/protocol.ts here now. The permission made a round trip worth recording. It was kind: 'execution' — "runs as the server owner and cannot be shared" — and a plugin permission has no kind, deliberately, because a permission nobody can delegate is a contradiction. So the property is expressed as ownerOnly: ['/'] instead: every path under this plugin refused to anyone but the owner. Same answer, reached from the paths rather than from a kind, and the first real use of a mechanism that landed the same day. The property is real — there is one physical screen and it is the owner's. Not finished, and BLOCKERS.md says so rather than the commit implying otherwise: the websocket is dormant because a plugin cannot claim a WebSocket provider, host setup needs a reboot and no manifest can express that, and there is no artwork. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
@@ -0,0 +1 @@
|
||||
node_modules/
|
||||
+46
@@ -0,0 +1,46 @@
|
||||
# Blockers — desktop extraction, 2026-08-21
|
||||
|
||||
Decisions taken without asking, and things that stop this being finished. Written as they were hit.
|
||||
|
||||
## 1. Host setup cannot be expressed by a manifest — left manual
|
||||
|
||||
`setup/setup-desktop.sh` installs `ubuntu-desktop` and `gdm3`, rewrites `/etc/gdm3/custom.conf` to force
|
||||
Xorg (x11vnc cannot mirror Wayland), enables auto-login so a session owns `:0`, installs Brave from its
|
||||
own apt repository, removes GNOME Keyring, and needs a **reboot**.
|
||||
|
||||
`osDependencies` installs packages. It cannot reconfigure a display manager, and nothing in the plugin
|
||||
contract can. So the manifest declares only `x11vnc` — the one honest package check — and the script is
|
||||
shipped for the owner to run by hand.
|
||||
|
||||
**This is the agreed next piece of plugin architecture**, deferred deliberately: the shape of a declared,
|
||||
sudo-run, reboot-aware setup step should be designed against a real case rather than guessed at, and this
|
||||
is that case. Until then the plugin installs and starts, and the desktop it mirrors has to exist already.
|
||||
|
||||
## 2. The websocket is not mounted, and a plugin cannot mount one
|
||||
|
||||
`api/websocket.ts` moved with everything else and is **dormant**. A plugin contributes `api/router.ts`
|
||||
(HTTP) and a sidecar; there is no way for it to claim a WebSocket provider — `pluginPermissions` in
|
||||
mount.ts sets `api` and `routes` and never `ws`, and `server.tsx`'s handler map is a literal.
|
||||
|
||||
It was already switched off in the platform (commented out since 2026-08-13), so nothing regressed. But
|
||||
`/desktop` cannot work again until either the plugin contract grows sockets or this is rewritten onto the
|
||||
sidecar proxy. Recorded rather than worked around.
|
||||
|
||||
## 3. No artwork
|
||||
|
||||
`assets/icon.png` and `assets/splash.png` are absent — I cannot draw them, and the marketplace and dock
|
||||
fall back to the manifest's `icon` glyph (`MonitorSmartphone`) plus `color`. The OfficerIcons repository
|
||||
has a `OffDesktop`-shaped gap too. Marked here so it is a known absence rather than a broken image.
|
||||
|
||||
## 4. The permission changed shape, deliberately
|
||||
|
||||
It was `kind: 'execution'` in the platform registry, meaning "runs as the server owner and cannot be
|
||||
shared". A plugin permission has no `kind` and the manifest contract refuses one, on the grounds that a
|
||||
permission nobody can delegate is a contradiction.
|
||||
|
||||
So it is expressed as `ownerOnly: ['/']` instead — every path under the plugin refused to anyone but the
|
||||
owner, which is the same answer by a different route. That mechanism landed the same day
|
||||
(`docs/plugin-route-authorization.md`) and this is its first real use.
|
||||
|
||||
The property being protected is real: x11vnc mirrors the single physical display the owner is logged
|
||||
into. Two accounts granted this would see the *same* screen, which is the owner's.
|
||||
@@ -0,0 +1,66 @@
|
||||
# Desktop
|
||||
|
||||
This machine's physical screen, mirrored into the browser. Extracted from the platform on 2026-08-21.
|
||||
|
||||
## What it is, and what it is not
|
||||
|
||||
x11vnc attached to display `:0` — **the session the owner is actually logged into**, not a second one.
|
||||
Officer used to install a desktop of its own (XFCE on a TigerVNC Xvnc server) and stopped: mirroring the
|
||||
real session means what you see remotely is what is on the screen, and there is one place for a thing to
|
||||
be rather than two.
|
||||
|
||||
That choice is why the permission is owner-only. There is one screen; two accounts granted this would see
|
||||
the same one, and it is the owner's.
|
||||
|
||||
## What moved
|
||||
|
||||
```
|
||||
src/servers/sidecar/vnc/ → sidecar/ x11vnc lifecycle, password provisioning
|
||||
src/servers/api/desktop/ → api/ one route, plus a dormant websocket
|
||||
officerdev/src/apps/Desktop/ → web/ the noVNC panel, header, wrapper
|
||||
scripts/setup-old/setup-desktop.sh → setup/ host setup, still run by hand
|
||||
```
|
||||
|
||||
It was **dormant when it moved**: the websocket was commented out in `server.tsx` and the router in
|
||||
`hono.ts` from 2026-08-13, and no `officer-vnc` process was running on any machine. This extraction moved
|
||||
switched-off code out of the platform. It did not break a working feature, and it did not restore one.
|
||||
|
||||
## What the platform lost, which is the point
|
||||
|
||||
The platform's `sidecar/protocol.ts` had a `// ── VNC ──` section: `vnc:start`, `vnc:ensure-password`,
|
||||
`vnc:stop`, their four reply variants, and `VncStartParams`/`VncSessionInfo`. `sidecar-registry.ts` had
|
||||
`startVnc`, `ensureVncPassword`, `stopVnc` and `isVncConnected`.
|
||||
|
||||
That is the platform knowing what a plugin is about — `CLAUDE.md` names it as a rule and this was its
|
||||
clearest violation. All of it lives in `sidecar/protocol.ts` here now.
|
||||
|
||||
What replaced it is generic: `sendSidecarCommand(kind, cmd)` and `isSidecarConnected(kind)`, which know
|
||||
that a command has a type and an id and a reply carries the same id, and nothing else. Any plugin's
|
||||
sidecar can be driven through them without a line changing in the platform.
|
||||
|
||||
## Host setup is not automatic
|
||||
|
||||
`setup/setup-desktop.sh` is run by hand, and the plugin cannot run it. See `BLOCKERS.md` §1 — the short
|
||||
version is that it rewrites GDM's config and needs a reboot, and a manifest can declare packages, not a
|
||||
reconfigured display manager.
|
||||
|
||||
The manifest declares `x11vnc` alone, which is the one part that *is* a package check and the one whose
|
||||
absence produces a sidecar that starts and immediately fails.
|
||||
|
||||
## Known gaps
|
||||
|
||||
`BLOCKERS.md` is the list. The two that matter:
|
||||
|
||||
- **the websocket is dormant** and a plugin cannot claim a WebSocket provider, so `/desktop` does not work
|
||||
yet — it did not work before the move either
|
||||
- **no artwork**; the glyph and colour in the manifest are the fallback
|
||||
|
||||
## Iris depends on the other half of this
|
||||
|
||||
`plugins/iris` captures pages using sessions from a browser profile at `~/.config/officer/browser-profile`
|
||||
— the profile a browser running **in this desktop** signs into. Its wrapper says "install the desktop
|
||||
plugin" when it finds no Chrome-family browser.
|
||||
|
||||
The browser relay (`src/servers/api/browser/`, `src/extensions/browser-relay/`) is a **separate**
|
||||
extraction, agreed as its own plugin and not started. This plugin's `setup-desktop.sh` installs Brave,
|
||||
which is what iris actually needs on the host.
|
||||
@@ -0,0 +1,22 @@
|
||||
# Desktop
|
||||
|
||||
Mirror this machine's display in the browser — the real session, not a second one.
|
||||
|
||||
Officer attaches to the physical screen the owner is logged into, so what you see remotely is what is on
|
||||
the monitor. There is one desktop, not a separate remote one that drifts from it.
|
||||
|
||||
**Owner only, and not by policy.** There is a single physical display and it belongs to the server owner.
|
||||
Every route in this plugin is refused to anyone else, because "share the desktop" would mean showing a
|
||||
second person the owner's own screen.
|
||||
|
||||
**It does not set up your desktop for you.** The plugin mirrors a graphical session that already exists.
|
||||
On a headless server there is nothing to mirror, and a script is included (`setup/setup-desktop.sh`) that
|
||||
installs GNOME, forces Xorg — x11vnc cannot capture Wayland — and enables auto-login so a session owns the
|
||||
display. It needs root and a reboot, so you run it yourself.
|
||||
|
||||
**Not working yet.** The desktop's WebSocket is not mounted: it was switched off in the platform before
|
||||
this became a plugin, and a plugin cannot currently claim a WebSocket provider. Installing this gets you
|
||||
the sidecar and the panel; the connection between them is the missing piece. `BLOCKERS.md` says exactly
|
||||
where it stands.
|
||||
|
||||
Requires `x11vnc`, which the installer checks for.
|
||||
@@ -0,0 +1,43 @@
|
||||
import { createRouter } from '@@/create-router';
|
||||
import { sendSidecarCommand, isSidecarConnected } from '@@/sidecar-registry';
|
||||
import { DESKTOP_SIDECAR_KIND, type DesktopEvent } from '../sidecar/protocol';
|
||||
|
||||
export const router = createRouter();
|
||||
|
||||
// The desktop UI asks for the password before it can open the WebSocket — and that WebSocket is what
|
||||
// starts the VNC session. So this cannot wait for a session to exist: on a fresh install nothing has
|
||||
// ever written the password, and answering "not configured" deadlocked the page permanently.
|
||||
//
|
||||
// Officer does not read the password file itself. It lives in the owner's ~/.vnc, next to the rfbauth
|
||||
// file x11vnc authenticates against, and the sidecar is the process that writes both — so it is the
|
||||
// process that answers for them too. `vnc:ensure-password` is idempotent: it returns the existing
|
||||
// pair when both files are already there, and provisions them when they are not.
|
||||
router.get('/vnc-password', async (ctx) => {
|
||||
const user = ctx.get('user');
|
||||
|
||||
if (!isSidecarConnected(DESKTOP_SIDECAR_KIND)) {
|
||||
return ctx.json({ error: 'VNC sidecar is not connected' }, 503);
|
||||
}
|
||||
|
||||
try {
|
||||
// Addressed through the platform's GENERIC door: it matches the reply by id and knows nothing about
|
||||
// what `vnc:ensure-password` means. The vocabulary is this plugin's — see sidecar/protocol.ts.
|
||||
const reply = await sendSidecarCommand<DesktopEvent>(DESKTOP_SIDECAR_KIND, {
|
||||
type: 'vnc:ensure-password',
|
||||
id: crypto.randomUUID(),
|
||||
email: user.email,
|
||||
});
|
||||
if (reply.type === 'vnc:error') throw new Error(reply.error);
|
||||
if (reply.type !== 'vnc:password') throw new Error(`unexpected reply ${reply.type}`);
|
||||
const password = reply.password;
|
||||
return ctx.json({ password });
|
||||
} catch (err) {
|
||||
const message = err instanceof Error ? err.message : 'Could not provision the VNC password';
|
||||
console.error('[desktop] VNC password provisioning failed:', message);
|
||||
return ctx.json({ error: message }, 500);
|
||||
}
|
||||
});
|
||||
|
||||
// GET /vnc-status is gone. It was never called — DesktopView asks only for /vnc-password — and it was
|
||||
// the sole reason the `vnc:status` command existed on the sidecar wire protocol at all. Noted as dead
|
||||
// by docs/sidecar-audit-2026-07.md months ago.
|
||||
@@ -0,0 +1,141 @@
|
||||
import { randomUUID } from 'node:crypto';
|
||||
import type { ServerWebSocket } from 'bun';
|
||||
import type { Socket } from 'bun';
|
||||
import { sendSidecarCommand } from '@@/sidecar-registry';
|
||||
import { DESKTOP_SIDECAR_KIND, type DesktopEvent } from '../sidecar/protocol';
|
||||
|
||||
type WSData = { userId: number; email: string; username: string; sessionId?: string };
|
||||
|
||||
type VncSession = {
|
||||
tcpSocket: Socket<{ ws: ServerWebSocket<WSData> }> | null;
|
||||
pendingMessages: Buffer[];
|
||||
};
|
||||
|
||||
const sessions = new Map<ServerWebSocket<WSData>, VncSession>();
|
||||
|
||||
/**
|
||||
* Start the mirror, through the platform's generic sidecar door.
|
||||
*
|
||||
* This was `sidecar.startVnc()` in the platform until the extraction. It lives here now because the
|
||||
* platform must not know what `vnc:start` means — see sidecar/protocol.ts.
|
||||
*/
|
||||
async function startVnc(params: { email: string; username: string; resolution?: string }) {
|
||||
const reply = await sendSidecarCommand<DesktopEvent>(DESKTOP_SIDECAR_KIND, {
|
||||
type: 'vnc:start',
|
||||
id: randomUUID(),
|
||||
params,
|
||||
});
|
||||
if (reply.type === 'vnc:error') throw new Error(reply.error);
|
||||
if (reply.type !== 'vnc:started') throw new Error(`unexpected reply ${reply.type}`);
|
||||
return { port: reply.port, display: reply.display };
|
||||
}
|
||||
|
||||
export const desktopWebsocket = {
|
||||
async open(ws: ServerWebSocket<WSData>) {
|
||||
const session: VncSession = { tcpSocket: null, pendingMessages: [] };
|
||||
sessions.set(ws, session);
|
||||
|
||||
let port: number;
|
||||
try {
|
||||
const result = await startVnc({
|
||||
email: ws.data.email,
|
||||
username: ws.data.username,
|
||||
});
|
||||
port = result.port;
|
||||
} catch (err) {
|
||||
const message = err instanceof Error ? err.message : 'Failed to start VNC session';
|
||||
console.error('[desktop] VNC start failed:', message);
|
||||
sessions.delete(ws);
|
||||
ws.close(4004, 'VNC server unavailable');
|
||||
return;
|
||||
}
|
||||
|
||||
try {
|
||||
const tcpSocket = await Bun.connect({
|
||||
hostname: '127.0.0.1',
|
||||
port,
|
||||
socket: {
|
||||
data(_socket, data) {
|
||||
try {
|
||||
ws.sendBinary(Buffer.from(data));
|
||||
} catch {
|
||||
// ws already closed
|
||||
}
|
||||
},
|
||||
close() {
|
||||
sessions.delete(ws);
|
||||
try {
|
||||
ws.close();
|
||||
} catch {
|
||||
/* ignore */
|
||||
}
|
||||
},
|
||||
error(_socket, err) {
|
||||
console.error('[desktop] TCP error:', err.message);
|
||||
sessions.delete(ws);
|
||||
try {
|
||||
ws.close();
|
||||
} catch {
|
||||
/* ignore */
|
||||
}
|
||||
},
|
||||
connectError(_socket, err) {
|
||||
console.error('[desktop] TCP connect error:', err.message);
|
||||
sessions.delete(ws);
|
||||
try {
|
||||
ws.close(4004, 'VNC server unavailable');
|
||||
} catch {
|
||||
/* ignore */
|
||||
}
|
||||
},
|
||||
open(socket) {
|
||||
for (const msg of session.pendingMessages) {
|
||||
socket.write(msg);
|
||||
}
|
||||
session.pendingMessages = [];
|
||||
},
|
||||
},
|
||||
data: { ws },
|
||||
});
|
||||
|
||||
session.tcpSocket = tcpSocket;
|
||||
} catch (err) {
|
||||
const message = err instanceof Error ? err.message : 'Failed to connect to VNC server';
|
||||
console.error('[desktop] VNC connect failed:', message);
|
||||
sessions.delete(ws);
|
||||
ws.close(4004, 'VNC server unavailable');
|
||||
}
|
||||
},
|
||||
|
||||
message(ws: ServerWebSocket<WSData>, raw: string | Buffer) {
|
||||
const session = sessions.get(ws);
|
||||
if (!session) return;
|
||||
|
||||
const data = typeof raw === 'string' ? Buffer.from(raw) : Buffer.from(raw);
|
||||
|
||||
if (!session.tcpSocket) {
|
||||
session.pendingMessages.push(data);
|
||||
return;
|
||||
}
|
||||
|
||||
try {
|
||||
session.tcpSocket.write(data);
|
||||
} catch {
|
||||
// ignore
|
||||
}
|
||||
},
|
||||
|
||||
close(ws: ServerWebSocket<WSData>) {
|
||||
const session = sessions.get(ws);
|
||||
if (session?.tcpSocket) {
|
||||
try {
|
||||
session.tcpSocket.end();
|
||||
} catch {
|
||||
// ignore
|
||||
}
|
||||
}
|
||||
sessions.delete(ws);
|
||||
},
|
||||
|
||||
drain() {},
|
||||
};
|
||||
+63
@@ -0,0 +1,63 @@
|
||||
import type { PluginManifest } from '@@/plugins/manifest';
|
||||
|
||||
// Desktop — this machine's physical screen, mirrored into the browser.
|
||||
//
|
||||
// Extracted from the platform on 2026-08-21, having been switched off since 2026-08-13: the websocket
|
||||
// was commented out in server.tsx, the router in hono.ts, and no `officer-vnc` process was running on
|
||||
// any machine. So this is dormant code moved out of the platform, not a working feature relocated.
|
||||
//
|
||||
// sidecar/ x11vnc against display :0, and the whole VNC contract
|
||||
// api/ one route — the password the UI needs before it can open the socket
|
||||
// web/ the noVNC panel, its header and the wrapper
|
||||
// setup/ the host setup this cannot do for itself — see PLUGIN.md
|
||||
//
|
||||
// ── It mirrors ONE screen, and it is the owner's ──
|
||||
//
|
||||
// x11vnc attaches to the single physical display the owner is logged into. There is no per-user session
|
||||
// here and there cannot be: two accounts granted this would see the SAME screen, which is the owner's,
|
||||
// including whatever is open on it. That is why the permission below is owner-only at every path rather
|
||||
// than merely grantable — the honest answer to "may a member have this" is no, and it is a property of
|
||||
// what the plugin does rather than a policy anyone should be able to relax.
|
||||
export const manifest: PluginManifest = {
|
||||
publisher: 'officerdev',
|
||||
version: '1.0.0',
|
||||
platform: '>=1.0.0',
|
||||
|
||||
label: 'Desktop',
|
||||
summary: 'Mirror this machine’s display in the browser — the real session, not a second one',
|
||||
icon: 'MonitorSmartphone',
|
||||
color: '#ec4899',
|
||||
|
||||
permissions: [
|
||||
{
|
||||
key: 'desktop',
|
||||
label: 'Desktop',
|
||||
description: "The server owner's physical screen, mirrored in the browser",
|
||||
// The whole surface, because every path here reaches the owner's own screen. `/` matches everything
|
||||
// under the plugin's prefix — see `isOwnerOnlyRoute`.
|
||||
//
|
||||
// This is what `kind: 'execution'` said while it was a core permission: "runs as the server owner
|
||||
// and cannot be shared". A plugin permission has no `kind` and deliberately never will, so the
|
||||
// property is expressed as paths instead. The registry entry it replaces is deleted, not both.
|
||||
ownerOnly: ['/'],
|
||||
},
|
||||
],
|
||||
|
||||
// x11vnc is the mirror itself. Declared so a machine without it refuses the install rather than
|
||||
// starting a sidecar that spawns a binary that is not there — and `dbus-x11` because the session it
|
||||
// attaches to needs one.
|
||||
//
|
||||
// NOT declared here: ubuntu-desktop, gdm3, the Xorg switch and auto-login. Those are not a package
|
||||
// check, they are a host reconfiguration that ends in a reboot, and `osDependencies` cannot express
|
||||
// one. `setup/setup-desktop.sh` does it and the owner runs it by hand. See BLOCKERS.md.
|
||||
//
|
||||
// `scope` is deliberately absent, meaning owner: x11vnc is spawned by this plugin's own sidecar, which
|
||||
// runs as the owner. No member ever invokes it, and there is nothing here a member could use.
|
||||
osDependencies: [
|
||||
{
|
||||
binary: 'x11vnc',
|
||||
reason: 'Mirrors the physical display. Without it the desktop cannot start at all.',
|
||||
packages: { apt: 'x11vnc', dnf: 'x11vnc', pacman: 'x11vnc' },
|
||||
},
|
||||
],
|
||||
};
|
||||
Executable
+173
@@ -0,0 +1,173 @@
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
# Officer Remote Desktop Setup — Ubuntu GNOME desktop on Xorg, mirrored over VNC.
|
||||
#
|
||||
# The platform mirrors the single physical display :0 with x11vnc (see vnc-manager.ts). x11vnc can only
|
||||
# capture an Xorg server, NOT a Wayland compositor — so we install the full GNOME desktop but force GDM
|
||||
# onto the Xorg session (WaylandEnable=false). Auto-login is enabled so a user session owns :0 for the
|
||||
# mirror to attach to. Switching the display manager takes effect on the next reboot.
|
||||
# Usage: ./scripts/setup/setup-desktop.sh
|
||||
|
||||
echo "=== Officer Remote Desktop Setup (Ubuntu GNOME on Xorg) ==="
|
||||
echo ""
|
||||
|
||||
DESKTOP_USER="$(whoami)"
|
||||
|
||||
# --- Step 1: Install GNOME desktop + GDM + x11vnc ---
|
||||
echo "[1/6] Installing ubuntu-desktop, GDM, x11vnc..."
|
||||
sudo apt update -qq
|
||||
sudo DEBIAN_FRONTEND=noninteractive apt install -y -qq \
|
||||
ubuntu-desktop \
|
||||
gdm3 \
|
||||
x11vnc \
|
||||
dbus-x11
|
||||
echo " Done."
|
||||
# No tigervnc package is needed. The VNC sidecar writes the .vnc/passwd rfbauth file with
|
||||
# `x11vnc -storepasswd` (see vnc-manager.ts). tigervnc-common was installed here for `vncpasswd`,
|
||||
# but it does not ship that binary — it only provides tigervncconfig — so the rfbauth file was never
|
||||
# created and the desktop could not authenticate.
|
||||
|
||||
# --- Step 2: Force GDM onto Xorg + enable auto-login (x11vnc cannot mirror Wayland) ---
|
||||
echo "[2/6] Forcing Xorg session and auto-login in GDM..."
|
||||
GDM_CONF=/etc/gdm3/custom.conf
|
||||
sudo mkdir -p /etc/gdm3
|
||||
[ -f "$GDM_CONF" ] || echo "[daemon]" | sudo tee "$GDM_CONF" > /dev/null
|
||||
# Ensure a [daemon] section exists to anchor the keys under.
|
||||
sudo grep -qE '^\[daemon\]' "$GDM_CONF" || echo "[daemon]" | sudo tee -a "$GDM_CONF" > /dev/null
|
||||
|
||||
# Set key=value under [daemon]: rewrite an existing (possibly commented) line, else insert after [daemon].
|
||||
set_gdm_key() {
|
||||
local key="$1" val="$2"
|
||||
if sudo grep -qE "^[[:space:]]*#?[[:space:]]*${key}=" "$GDM_CONF"; then
|
||||
sudo sed -i "s|^[[:space:]]*#\?[[:space:]]*${key}=.*|${key}=${val}|" "$GDM_CONF"
|
||||
else
|
||||
sudo sed -i "/^\[daemon\]/a ${key}=${val}" "$GDM_CONF"
|
||||
fi
|
||||
}
|
||||
|
||||
set_gdm_key WaylandEnable false
|
||||
set_gdm_key AutomaticLoginEnable true
|
||||
set_gdm_key AutomaticLogin "$DESKTOP_USER"
|
||||
echo " Xorg forced (WaylandEnable=false), auto-login as $DESKTOP_USER."
|
||||
|
||||
# --- Step 3: Make GDM the default display manager ---
|
||||
echo "[3/6] Setting GDM as the default display manager..."
|
||||
echo "/usr/sbin/gdm3" | sudo tee /etc/X11/default-display-manager > /dev/null
|
||||
sudo systemctl enable gdm3 >/dev/null 2>&1 || sudo systemctl enable gdm >/dev/null 2>&1 || true
|
||||
sudo systemctl set-default graphical.target >/dev/null 2>&1 || true
|
||||
# Disable any prior display manager so it doesn't fight GDM. lightdm is named because earlier versions
|
||||
# of this script installed XFCE; a host set up back then still has it and it would win the boot race.
|
||||
sudo systemctl disable lightdm >/dev/null 2>&1 || true
|
||||
echo " Done (takes effect on next reboot)."
|
||||
|
||||
# --- Step 4: Install Brave browser (native .deb, not snap) ---
|
||||
echo "[4/6] Installing Brave browser..."
|
||||
if ! command -v brave-browser-stable > /dev/null 2>&1; then
|
||||
sudo curl -fsSLo /usr/share/keyrings/brave-browser-archive-keyring.gpg \
|
||||
https://brave-browser-apt-release.s3.brave.com/brave-browser-archive-keyring.gpg
|
||||
echo "deb [signed-by=/usr/share/keyrings/brave-browser-archive-keyring.gpg] https://brave-browser-apt-release.s3.brave.com/ stable main" \
|
||||
| sudo tee /etc/apt/sources.list.d/brave-browser-release.list > /dev/null
|
||||
sudo apt update -qq
|
||||
sudo DEBIAN_FRONTEND=noninteractive apt install -y -qq brave-browser
|
||||
fi
|
||||
# Fix launcher symlink
|
||||
if [ -f /opt/brave.com/brave/brave-browser ]; then
|
||||
sudo rm -f /usr/bin/brave-browser-stable
|
||||
sudo ln -s /opt/brave.com/brave/brave-browser /usr/bin/brave-browser-stable
|
||||
fi
|
||||
# Tell Brave to use basic password store (no keyring prompts)
|
||||
sudo mkdir -p /etc/brave
|
||||
echo '--password-store=basic' | sudo tee /etc/brave/brave-flags.conf > /dev/null
|
||||
echo " Done."
|
||||
|
||||
# --- Step 5: Remove GNOME Keyring + set default browser (prevents password prompts on login) ---
|
||||
echo "[5/6] Removing GNOME Keyring and setting default browser..."
|
||||
sudo apt remove -y --purge gnome-keyring > /dev/null 2>&1 || true
|
||||
rm -rf ~/.local/share/keyrings
|
||||
if command -v brave-browser-stable > /dev/null 2>&1; then
|
||||
sudo update-alternatives --set x-www-browser /opt/brave.com/brave/brave 2>/dev/null || true
|
||||
echo " Brave set as default."
|
||||
else
|
||||
echo " No supported browser found, skipping default."
|
||||
fi
|
||||
|
||||
# --- Step 6: Headless display (keep a desktop when no monitor is attached) ---
|
||||
echo "[6/6] Configuring the headless display..."
|
||||
|
||||
# x11vnc mirrors :0, but with nothing plugged in the connector has no EDID and no CRTC, so GNOME
|
||||
# renders nothing and the mirror is black. Replaying a real monitor's EDID makes the connector look
|
||||
# permanently attached. The EDID has to be captured from a screen that is plugged in *now* — there is
|
||||
# nothing to copy otherwise — so this step is skipped on a headless run and can be re-run later.
|
||||
EDID_DIR=/lib/firmware/edid
|
||||
EDID_FILE="$EDID_DIR/officer-screen.bin"
|
||||
CONNECTED_SYSFS=""
|
||||
for c in /sys/class/drm/card*-*/status; do
|
||||
[ "$(cat "$c" 2>/dev/null)" = "connected" ] || continue
|
||||
CONNECTED_SYSFS="$(basename "$(dirname "$c")")"
|
||||
break
|
||||
done
|
||||
|
||||
if [ -z "$CONNECTED_SYSFS" ] && [ ! -f "$EDID_FILE" ]; then
|
||||
echo " ! No display connected and no EDID saved — skipping."
|
||||
echo " Plug a monitor in and re-run this script to capture one, otherwise the remote"
|
||||
echo " desktop will be black whenever nothing is attached."
|
||||
else
|
||||
# cardN-HDMI-A-1 -> HDMI-A-1, which is the name the kernel parameters use (card numbering can
|
||||
# change between boots; the connector name does not).
|
||||
if [ -n "$CONNECTED_SYSFS" ]; then
|
||||
CONNECTOR="${CONNECTED_SYSFS#*-}"
|
||||
sudo mkdir -p "$EDID_DIR"
|
||||
sudo cp "/sys/class/drm/$CONNECTED_SYSFS/edid" "$EDID_FILE"
|
||||
echo " Captured EDID from $CONNECTOR ($(stat -c%s "$EDID_FILE") bytes)."
|
||||
echo "$CONNECTOR" | sudo tee "$EDID_DIR/officer-connector" > /dev/null
|
||||
else
|
||||
CONNECTOR="$(cat "$EDID_DIR/officer-connector" 2>/dev/null || echo HDMI-A-1)"
|
||||
echo " Reusing the saved EDID for $CONNECTOR."
|
||||
fi
|
||||
|
||||
# drm.edid_firmware makes the connector report that EDID; the trailing "e" on video= forces it
|
||||
# enabled with nothing attached. amdgpu is not in the initramfs, so /lib/firmware is readable by
|
||||
# the time the driver loads and no initramfs rebuild is needed.
|
||||
KERNEL_ARGS="drm.edid_firmware=$CONNECTOR:edid/officer-screen.bin video=$CONNECTOR:1920x1080e"
|
||||
if grep -q "drm.edid_firmware=" /etc/default/grub; then
|
||||
echo " GRUB already carries a forced EDID — leaving it alone."
|
||||
else
|
||||
sudo cp /etc/default/grub "/etc/default/grub.bak-$(date +%Y%m%d%H%M%S)"
|
||||
CURRENT=$(grep "^GRUB_CMDLINE_LINUX_DEFAULT=" /etc/default/grub | sed 's/^[^"]*"//; s/"$//')
|
||||
sudo sed -i "s|^GRUB_CMDLINE_LINUX_DEFAULT=.*|GRUB_CMDLINE_LINUX_DEFAULT=\"${CURRENT:+$CURRENT }$KERNEL_ARGS\"|" /etc/default/grub
|
||||
sudo update-grub > /dev/null 2>&1
|
||||
echo " Added the forced EDID to the kernel command line (takes effect on reboot)."
|
||||
fi
|
||||
|
||||
# The EDID's preferred mode is whatever the captured panel was, which may be small. GNOME picks
|
||||
# preferred, so raise it at session start.
|
||||
install -d "$HOME/.local/bin" "$HOME/.config/autostart"
|
||||
install -m 755 "$(dirname "$0")/officer-set-display.sh" "$HOME/.local/bin/officer-set-display.sh"
|
||||
cat > "$HOME/.config/autostart/officer-set-display.desktop" <<AUTOSTART
|
||||
[Desktop Entry]
|
||||
Type=Application
|
||||
Name=Officer display mode
|
||||
Comment=Raise the headless display to its largest usable mode at login
|
||||
Exec=$HOME/.local/bin/officer-set-display.sh
|
||||
X-GNOME-Autostart-enabled=true
|
||||
NoDisplay=true
|
||||
AUTOSTART
|
||||
echo " Installed the login-time mode setter."
|
||||
fi
|
||||
echo " Done."
|
||||
|
||||
# --- Cleanup old systemd service if it exists ---
|
||||
if systemctl list-unit-files officer-vnc.service &>/dev/null; then
|
||||
echo ""
|
||||
echo "Removing old officer-vnc systemd service..."
|
||||
sudo systemctl stop officer-vnc 2>/dev/null || true
|
||||
sudo systemctl disable officer-vnc 2>/dev/null || true
|
||||
sudo rm -f /etc/systemd/system/officer-vnc.service
|
||||
sudo systemctl daemon-reload
|
||||
echo " Done."
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "Setup complete. The screen mirror (x11vnc on :0) is managed by the VNC sidecar."
|
||||
echo "REBOOT to switch into the GNOME-on-Xorg session with auto-login."
|
||||
@@ -0,0 +1,73 @@
|
||||
import type { DesktopCommand, DesktopEvent } from './protocol';
|
||||
import { DESKTOP_SIDECAR_KIND } from './protocol';
|
||||
import * as vncManager from './vnc-manager';
|
||||
import { createSidecarConnector } from '@@/sidecar/connect';
|
||||
import { getOwnerHomeDir } from '@@/data-path';
|
||||
import { API_URL } from '@@/officer-url.mjs';
|
||||
|
||||
// ── Command handlers ──
|
||||
|
||||
type ReplyFn = (msg: DesktopEvent) => void;
|
||||
|
||||
async function handleCommand(cmd: DesktopCommand, reply: ReplyFn) {
|
||||
switch (cmd.type) {
|
||||
case 'ping':
|
||||
reply({ type: 'pong', id: cmd.id });
|
||||
break;
|
||||
|
||||
case 'vnc:start': {
|
||||
try {
|
||||
const { port, display } = await vncManager.startSession(cmd.params);
|
||||
reply({ type: 'vnc:started', id: cmd.id, port, display });
|
||||
} catch (err) {
|
||||
reply({ type: 'vnc:error', id: cmd.id, error: err instanceof Error ? err.message : String(err) });
|
||||
}
|
||||
break;
|
||||
}
|
||||
|
||||
case 'vnc:ensure-password': {
|
||||
try {
|
||||
const { password } = await vncManager.ensureVncPassword(getOwnerHomeDir(cmd.email));
|
||||
reply({ type: 'vnc:password', id: cmd.id, password });
|
||||
} catch (err) {
|
||||
reply({ type: 'vnc:error', id: cmd.id, error: err instanceof Error ? err.message : String(err) });
|
||||
}
|
||||
break;
|
||||
}
|
||||
|
||||
case 'vnc:stop':
|
||||
vncManager.stopSession(cmd.email);
|
||||
reply({ type: 'vnc:stopped', id: cmd.id });
|
||||
break;
|
||||
|
||||
default:
|
||||
reply({
|
||||
type: 'error',
|
||||
id: (cmd as DesktopCommand).id,
|
||||
error: `Unknown command type: ${(cmd as Record<string, unknown>).type}`,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// ── Connect to API server ──
|
||||
|
||||
const connection = createSidecarConnector({
|
||||
apiUrl: `${API_URL}/api/sidecar/register`,
|
||||
name: 'vnc',
|
||||
handles: [DESKTOP_SIDECAR_KIND],
|
||||
onCommand(cmd, reply) {
|
||||
handleCommand(cmd as DesktopCommand, reply as ReplyFn);
|
||||
},
|
||||
});
|
||||
|
||||
// ── Graceful shutdown ──
|
||||
|
||||
function shutdown(signal: string) {
|
||||
console.log(`[vnc] ${signal} received, stopping all sessions...`);
|
||||
vncManager.stopAll();
|
||||
connection.destroy();
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
process.on('SIGTERM', () => shutdown('SIGTERM'));
|
||||
process.on('SIGINT', () => shutdown('SIGINT'));
|
||||
@@ -0,0 +1,44 @@
|
||||
// The desktop sidecar's own vocabulary.
|
||||
//
|
||||
// These types lived in the PLATFORM's `sidecar/protocol.ts` until the extraction, alongside `vnc:start`
|
||||
// and `vnc:password` variants in its command and event unions. That is the thing CLAUDE.md warns about
|
||||
// most plainly — "the platform must not know what your plugin is about. Not just its code, its
|
||||
// VOCABULARY" — and it is why the platform grew a generic `sendSidecarCommand` instead: it knows a
|
||||
// command has a type and an id, and nothing else.
|
||||
|
||||
export type VncStartParams = {
|
||||
email: string;
|
||||
username: string;
|
||||
resolution?: string;
|
||||
};
|
||||
|
||||
export type VncSessionInfo = {
|
||||
email: string;
|
||||
display: number;
|
||||
port: number;
|
||||
pid: number;
|
||||
alive: boolean;
|
||||
};
|
||||
|
||||
/** What this plugin sends to its sidecar. `id` is what the reply is matched on. */
|
||||
export type DesktopCommand =
|
||||
// Every sidecar answers this; the connector uses it as a liveness check.
|
||||
| { type: 'ping'; id: string }
|
||||
| { type: 'vnc:start'; id: string; params: VncStartParams }
|
||||
// Provision the password WITHOUT starting a server — the UI needs it before it can open the socket
|
||||
// that would start one, so asking `vnc:start` here would be circular.
|
||||
| { type: 'vnc:ensure-password'; id: string; email: string }
|
||||
| { type: 'vnc:stop'; id: string; email: string };
|
||||
|
||||
/** What the sidecar sends back. */
|
||||
export type DesktopEvent =
|
||||
| { type: 'pong'; id: string }
|
||||
// The generic failure, for a command this sidecar does not recognise.
|
||||
| { type: 'error'; id: string; error: string }
|
||||
| { type: 'vnc:started'; id: string; port: number; display: number }
|
||||
| { type: 'vnc:password'; id: string; password: string }
|
||||
| { type: 'vnc:stopped'; id: string }
|
||||
| { type: 'vnc:error'; id: string; error: string };
|
||||
|
||||
/** The `handles` key this sidecar registers under, and the one the api addresses it by. */
|
||||
export const DESKTOP_SIDECAR_KIND = 'vnc';
|
||||
@@ -0,0 +1,346 @@
|
||||
import { existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
import type { VncStartParams, VncSessionInfo } from './protocol';
|
||||
import { getOwnerHomeDir } from '@@/data-path';
|
||||
|
||||
// Mirrors the physical display instead of spawning a virtual desktop per user, so the
|
||||
// browser shows the same session as the screen. There is one seat, hence one shared
|
||||
// mirror — the first caller's VNC password is the one it answers with.
|
||||
const MIRROR_PORT = 5900;
|
||||
const READY_TIMEOUT_MS = 5000;
|
||||
// Above this framebuffer width the stream is halved; at or below it, pixels are served 1:1.
|
||||
const SCALE_ABOVE_WIDTH = 2560;
|
||||
|
||||
// The display number is NOT fixed. Under LightDM the user session got :0, so this was hardcoded to it.
|
||||
// GDM gives :0 to its own greeter and starts the user's Xorg with -displayfd, letting the kernel pick —
|
||||
// in practice :1. Hardcoding :0 made the mirror fail with "Can't open display" on every GNOME machine.
|
||||
//
|
||||
// Find it by socket ownership instead: /tmp/.X11-unix/X<n> is owned by whoever runs that X server, so
|
||||
// the one owned by us is the owner's session and any other is the greeter's. Fall back to the lowest
|
||||
// socket (covers a root-run Xorg, as LightDM did) and finally to :0 so behaviour never gets worse than
|
||||
// the constant it replaced.
|
||||
function resolveDisplayNum(): number {
|
||||
const uid = typeof process.getuid === 'function' ? process.getuid() : null;
|
||||
let sockets: number[] = [];
|
||||
try {
|
||||
sockets = readdirSync('/tmp/.X11-unix')
|
||||
.filter((n) => /^X\d+$/.test(n))
|
||||
.map((n) => Number(n.slice(1)))
|
||||
.sort((a, b) => a - b);
|
||||
} catch {
|
||||
return 0;
|
||||
}
|
||||
if (uid != null) {
|
||||
const own = sockets.find((n) => {
|
||||
try {
|
||||
return statSync(`/tmp/.X11-unix/X${n}`).uid === uid;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
});
|
||||
if (own !== undefined) return own;
|
||||
}
|
||||
return sockets[0] ?? 0;
|
||||
}
|
||||
|
||||
// x11vnc reads the display's cookie from the logged-in user's X authority, so no root is needed. Where
|
||||
// that cookie lives depends on the display manager: GDM (Ubuntu GNOME on Xorg) keeps it in the
|
||||
// per-session dir /run/user/<uid>/gdm/Xauthority; LightDM (or a manual startx) uses the classic
|
||||
// ~/.Xauthority. Try the GDM path first, then fall back. While the greeter owns the seat the user's
|
||||
// cookie doesn't exist yet and mirroring fails until someone is logged in.
|
||||
function resolveXauthority(): string | null {
|
||||
const uid = typeof process.getuid === 'function' ? process.getuid() : null;
|
||||
const candidates = [
|
||||
uid != null ? `/run/user/${uid}/gdm/Xauthority` : null,
|
||||
join(process.env.HOME ?? '', '.Xauthority'),
|
||||
].filter((p): p is string => Boolean(p));
|
||||
return candidates.find((p) => existsSync(p)) ?? null;
|
||||
}
|
||||
|
||||
type MirrorSession = {
|
||||
email: string;
|
||||
username: string;
|
||||
display: number;
|
||||
port: number;
|
||||
pid: number;
|
||||
};
|
||||
|
||||
let mirror: MirrorSession | null = null;
|
||||
|
||||
function isProcessAlive(pid: number): boolean {
|
||||
try {
|
||||
process.kill(pid, 0);
|
||||
return true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
// Provision the pair of files a VNC session needs: `password` in plaintext, which the API hands to
|
||||
// the browser, and `passwd` in rfbauth format, which x11vnc authenticates against. Idempotent —
|
||||
// returns the existing password when both are already present.
|
||||
//
|
||||
// x11vnc writes the rfbauth file itself via -storepasswd. This used to shell out to tigervnc's
|
||||
// `vncpasswd -f`, which is not installed by default (and is not in tigervnc-common, despite what
|
||||
// setup-desktop.sh claimed), so the rfbauth file silently never appeared — the failure was swallowed
|
||||
// because only a zero exit code triggered the write.
|
||||
export async function ensureVncPassword(homeDir: string): Promise<{ password: string; passwdFile: string }> {
|
||||
const vncDir = join(homeDir, '.vnc');
|
||||
const passwdFile = join(vncDir, 'passwd');
|
||||
const plainFile = join(vncDir, 'password');
|
||||
|
||||
if (existsSync(passwdFile) && existsSync(plainFile)) {
|
||||
const password = (await Bun.file(plainFile).text()).trim();
|
||||
if (password) return { password, passwdFile };
|
||||
}
|
||||
|
||||
mkdirSync(vncDir, { recursive: true });
|
||||
|
||||
// 8 printable ASCII characters. VNC truncates to 8, so there is no point generating more.
|
||||
const password = Array.from(crypto.getRandomValues(new Uint8Array(8)))
|
||||
.map((b) => String.fromCharCode(33 + (b % 94)))
|
||||
.join('');
|
||||
|
||||
await Bun.write(plainFile, password);
|
||||
|
||||
const proc = Bun.spawnSync({
|
||||
cmd: ['x11vnc', '-storepasswd', password, passwdFile],
|
||||
stdout: 'ignore',
|
||||
stderr: 'pipe',
|
||||
});
|
||||
if (proc.exitCode !== 0 || !existsSync(passwdFile)) {
|
||||
const stderr = proc.stderr.toString().trim();
|
||||
throw new Error(`Could not write the VNC password file: ${stderr || 'x11vnc -storepasswd failed'}`);
|
||||
}
|
||||
|
||||
Bun.spawnSync({ cmd: ['chmod', '600', passwdFile], stdout: 'ignore', stderr: 'ignore' });
|
||||
Bun.spawnSync({ cmd: ['chmod', '600', plainFile], stdout: 'ignore', stderr: 'ignore' });
|
||||
|
||||
console.log(`[vnc] provisioned VNC password at ${vncDir}`);
|
||||
return { password, passwdFile };
|
||||
}
|
||||
|
||||
type Geometry = { w: number; h: number; x: number; y: number };
|
||||
type DisplayGeometry = { framebufferWidth: number | null; primary: Geometry | null; connected: number };
|
||||
|
||||
// X composes every attached output into ONE framebuffer, so with two monitors side by side the
|
||||
// framebuffer is their combined width and mirroring it whole sends both screens squashed together.
|
||||
// Read the layout so the caller can clip to a single output.
|
||||
//
|
||||
// Returns nulls when xrandr is missing or X is not up; callers treat that as "don't scale, don't clip",
|
||||
// because serving too many pixels beats serving nothing.
|
||||
function readDisplayGeometry(xauthority: string, display: string): DisplayGeometry {
|
||||
const proc = Bun.spawnSync({
|
||||
cmd: ['xrandr', '--current'],
|
||||
env: { ...process.env, DISPLAY: display, XAUTHORITY: xauthority },
|
||||
stdout: 'pipe',
|
||||
stderr: 'ignore',
|
||||
});
|
||||
if (proc.exitCode !== 0) return { framebufferWidth: null, primary: null, connected: 0 };
|
||||
|
||||
const out = proc.stdout.toString();
|
||||
const fb = out.match(/current\s+(\d+)\s*x\s*(\d+)/);
|
||||
// Count ENABLED outputs, not merely connected ones: a screen that is plugged in but switched off
|
||||
// still reports "connected" and contributes nothing to the framebuffer. Only an enabled output
|
||||
// carries a WxH+X+Y geometry, so requiring that is what distinguishes the two.
|
||||
const connected = (out.match(/^\S+ connected(?: primary)? \d+x\d+\+\d+\+\d+/gm) ?? []).length;
|
||||
|
||||
// "HDMI-A-0 connected primary 3840x2160+0+0 (normal left ..." — the geometry only appears on an
|
||||
// output that is actually enabled, so a connected-but-off output correctly yields no match.
|
||||
const p = out.match(/^\S+ connected primary (\d+)x(\d+)\+(\d+)\+(\d+)/m);
|
||||
const primary = p ? { w: Number(p[1]), h: Number(p[2]), x: Number(p[3]), y: Number(p[4]) } : null;
|
||||
|
||||
return { framebufferWidth: fb ? Number(fb[1]) : null, primary, connected };
|
||||
}
|
||||
|
||||
async function isPortOpen(port: number): Promise<boolean> {
|
||||
try {
|
||||
const socket = await Bun.connect({
|
||||
hostname: '127.0.0.1',
|
||||
port,
|
||||
socket: { data() {}, error() {} },
|
||||
});
|
||||
socket.end();
|
||||
return true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
// A listener on the port is NOT proof our server started. The running mirror lives in module state, so
|
||||
// a sidecar restart forgets it while the process keeps running orphaned — and then this check sees the
|
||||
// ORPHAN listening and reports success, leaving the platform convinced it started something the browser
|
||||
// is not looking at. That is not hypothetical: on 2026-08-01 an Xvnc left over from the virtual-desktop
|
||||
// experiment held 5900, and the mirror reported healthy while the browser was served a stale XFCE
|
||||
// session. So reclaim the port first, and treat our own process dying as failure.
|
||||
async function reclaimPort(port: number): Promise<void> {
|
||||
if (!(await isPortOpen(port))) return;
|
||||
|
||||
console.log(`[vnc] port ${port} already held — killing the orphan before starting`);
|
||||
Bun.spawnSync({ cmd: ['fuser', '-k', '-TERM', `${port}/tcp`], stdout: 'ignore', stderr: 'ignore' });
|
||||
|
||||
for (let i = 0; i < 20; i++) {
|
||||
await Bun.sleep(100);
|
||||
if (!(await isPortOpen(port))) return;
|
||||
}
|
||||
|
||||
Bun.spawnSync({ cmd: ['fuser', '-k', '-KILL', `${port}/tcp`], stdout: 'ignore', stderr: 'ignore' });
|
||||
await Bun.sleep(300);
|
||||
}
|
||||
|
||||
// x11vnc stays in the foreground, so readiness is the listening port rather than exit code — but only
|
||||
// once we know the process we spawned is the one alive to own it.
|
||||
async function waitForPort(port: number, proc: { exitCode: number | null }): Promise<boolean> {
|
||||
const deadline = Date.now() + READY_TIMEOUT_MS;
|
||||
while (Date.now() < deadline) {
|
||||
if (proc.exitCode !== null) return false;
|
||||
if (await isPortOpen(port)) return true;
|
||||
await Bun.sleep(100);
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
export async function startSession(params: VncStartParams): Promise<{ port: number; display: number }> {
|
||||
if (mirror && isProcessAlive(mirror.pid)) {
|
||||
return { port: mirror.port, display: mirror.display };
|
||||
}
|
||||
mirror = null;
|
||||
|
||||
const homeDir = getOwnerHomeDir(params.email);
|
||||
const { passwdFile } = await ensureVncPassword(homeDir);
|
||||
|
||||
// An orphan from a previous sidecar life would still hold the port and be mistaken for a healthy start.
|
||||
await reclaimPort(MIRROR_PORT);
|
||||
|
||||
const displayNum = resolveDisplayNum();
|
||||
const display = `:${displayNum}`;
|
||||
|
||||
const xauthority = resolveXauthority();
|
||||
if (!xauthority) {
|
||||
throw new Error(`No X authority found (GDM or ~/.Xauthority) — nobody is logged in on ${display}`);
|
||||
}
|
||||
|
||||
// With more than one output attached the framebuffer spans them all, and mirroring it whole shows
|
||||
// every monitor side by side, squashed. Clip to the primary so the remote view is one screen at the
|
||||
// right proportions. Only when a primary is actually marked and there is more than one output —
|
||||
// otherwise the framebuffer already IS the single screen and clipping would just add a failure mode.
|
||||
const geo = readDisplayGeometry(xauthority, display);
|
||||
const clipTo = geo.connected > 1 && geo.primary ? geo.primary : null;
|
||||
const clip = clipTo ? ['-clip', `${clipTo.w}x${clipTo.h}+${clipTo.x}+${clipTo.y}`] : [];
|
||||
if (clipTo) {
|
||||
console.log(`[vnc] ${geo.connected} outputs attached — clipping to the primary ${clip[1]}`);
|
||||
}
|
||||
|
||||
// Halving a 4K screen keeps the stream sane over the tailnet, but the same 0.5 applied to a small
|
||||
// screen is just lost detail — and with no monitor plugged in, X falls back to something tiny
|
||||
// (800x480 here), which halves to an unreadable 400x240. Scale only when there is genuinely too much
|
||||
// to send, and judge that on what is actually being served: the clip if there is one, else the
|
||||
// whole framebuffer.
|
||||
const width = clipTo ? clipTo.w : geo.framebufferWidth;
|
||||
const scale = width !== null && width > SCALE_ABOVE_WIDTH ? ['-scale', '0.5'] : [];
|
||||
if (width !== null) {
|
||||
console.log(`[vnc] serving ${width}px wide — ${scale.length ? 'scaling to 50%' : '1:1'}`);
|
||||
}
|
||||
|
||||
const proc = Bun.spawn({
|
||||
cmd: [
|
||||
'x11vnc',
|
||||
'-display',
|
||||
display,
|
||||
'-auth',
|
||||
xauthority,
|
||||
'-rfbport',
|
||||
String(MIRROR_PORT),
|
||||
'-rfbauth',
|
||||
passwdFile,
|
||||
'-localhost',
|
||||
'-forever',
|
||||
'-shared',
|
||||
...clip,
|
||||
...scale,
|
||||
// No -noxdamage. It was set when this was written, with no recorded reason, and it is expensive:
|
||||
// without the DAMAGE extension x11vnc cannot be told which rectangles changed, so it polls the
|
||||
// WHOLE framebuffer continuously to find out. That makes cost scale with screen area rather than
|
||||
// with what actually moved — on a 4K mirror it is the single biggest source of latency, and it is
|
||||
// why a smaller machine felt instant by comparison. This X server reports DAMAGE, MIT-SHM and
|
||||
// XFIXES, so the optimisation is genuinely available.
|
||||
//
|
||||
// If stale patches ever appear on screen (some drivers under-report damage), putting -noxdamage
|
||||
// back is the fix — at the cost of the polling above.
|
||||
'-quiet',
|
||||
],
|
||||
stdout: 'ignore',
|
||||
stderr: 'pipe',
|
||||
});
|
||||
|
||||
// Drain stderr so the pipe cannot fill and stall x11vnc; keep the tail for errors
|
||||
let stderrTail = '';
|
||||
(async () => {
|
||||
const reader = (proc.stderr as ReadableStream<Uint8Array>).getReader();
|
||||
const decoder = new TextDecoder();
|
||||
try {
|
||||
while (true) {
|
||||
const { done, value } = await reader.read();
|
||||
if (done) break;
|
||||
stderrTail = (stderrTail + decoder.decode(value, { stream: true })).slice(-2000);
|
||||
}
|
||||
} catch {
|
||||
// process ended
|
||||
}
|
||||
})();
|
||||
|
||||
if (!(await waitForPort(MIRROR_PORT, proc))) {
|
||||
try {
|
||||
proc.kill();
|
||||
} catch {
|
||||
// already dead
|
||||
}
|
||||
throw new Error(`x11vnc failed to listen on ${MIRROR_PORT}: ${stderrTail.trim() || 'timed out'}`);
|
||||
}
|
||||
|
||||
mirror = {
|
||||
email: params.email,
|
||||
username: params.username ?? '',
|
||||
display: displayNum,
|
||||
port: MIRROR_PORT,
|
||||
pid: proc.pid,
|
||||
};
|
||||
console.log(`[vnc] mirroring ${display} on port ${MIRROR_PORT} (pid ${proc.pid})`);
|
||||
|
||||
return { port: MIRROR_PORT, display: displayNum };
|
||||
}
|
||||
|
||||
export function stopSession(_email: string): void {
|
||||
if (!mirror) return;
|
||||
|
||||
try {
|
||||
process.kill(mirror.pid);
|
||||
} catch {
|
||||
// already dead
|
||||
}
|
||||
|
||||
console.log(`[vnc] stopped mirror of :${mirror.display} (pid ${mirror.pid})`);
|
||||
mirror = null;
|
||||
}
|
||||
|
||||
export function getSession(_email: string): VncSessionInfo | null {
|
||||
if (!mirror) return null;
|
||||
|
||||
const alive = mirror.pid > 0 && isProcessAlive(mirror.pid);
|
||||
if (!alive) {
|
||||
mirror = null;
|
||||
return null;
|
||||
}
|
||||
|
||||
return {
|
||||
email: mirror.email,
|
||||
display: mirror.display,
|
||||
port: mirror.port,
|
||||
pid: mirror.pid,
|
||||
alive,
|
||||
};
|
||||
}
|
||||
|
||||
export function stopAll(): void {
|
||||
stopSession('');
|
||||
}
|
||||
@@ -0,0 +1,10 @@
|
||||
import { MonitorSmartphone } from 'lucide-react';
|
||||
|
||||
export const DesktopHeader = () => {
|
||||
return (
|
||||
<>
|
||||
<MonitorSmartphone className="h-3.5 w-3.5 shrink-0" />
|
||||
<span className="text-xs font-medium shrink-0">Remote Desktop</span>
|
||||
</>
|
||||
);
|
||||
};
|
||||
@@ -0,0 +1,225 @@
|
||||
import type { CSSProperties } from 'react';
|
||||
import { useEffect, useRef, useState } from 'react';
|
||||
import { useClient } from 'hooks/useClient';
|
||||
import { useMounted } from 'hooks/useMounted';
|
||||
|
||||
export type DesktopViewProps = {
|
||||
className?: string;
|
||||
style?: CSSProperties;
|
||||
};
|
||||
|
||||
// The BUNDLE, not public/novnc/rfb.js. That entry is unbundled noVNC source: 42 ES modules whose
|
||||
// imports nest six levels deep, so a native dynamic import made the browser walk the graph — fetch,
|
||||
// parse, discover the next level, fetch again. Six sequential round trips and 42 requests before the
|
||||
// desktop could even begin connecting, which over the tailnet is seconds, and a hard refresh pays it
|
||||
// every time. One file is one round trip.
|
||||
//
|
||||
// Regenerate after updating vendored noVNC:
|
||||
// bun build public/novnc/rfb.js --outfile=public/novnc/rfb.bundle.js --format=esm --minify --target=browser
|
||||
const NOVNC_URL = '/novnc/rfb.bundle.js';
|
||||
|
||||
const buildWsUrl = () => {
|
||||
const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
|
||||
const token = localStorage.getItem('BEARER_TOKEN') ?? '';
|
||||
return `${protocol}//${window.location.host}/api/desktop/ws?token=${encodeURIComponent(token)}`;
|
||||
};
|
||||
|
||||
type RFBInstance = {
|
||||
resizeSession: boolean;
|
||||
scaleViewport: boolean;
|
||||
showDotCursor: boolean;
|
||||
focusOnClick: boolean;
|
||||
disconnect: () => void;
|
||||
sendCredentials: (creds: { password: string }) => void;
|
||||
addEventListener: (type: string, listener: (ev: CustomEvent) => void) => void;
|
||||
};
|
||||
|
||||
let rfbModulePromise: Promise<{
|
||||
default: new (target: HTMLElement, url: string, options?: { credentials?: { password?: string } }) => RFBInstance;
|
||||
}> | null = null;
|
||||
|
||||
const loadRFB = () => {
|
||||
if (!rfbModulePromise) {
|
||||
rfbModulePromise = import(/* @vite-ignore */ NOVNC_URL) as NonNullable<typeof rfbModulePromise>;
|
||||
}
|
||||
return rfbModulePromise!;
|
||||
};
|
||||
|
||||
export const DesktopView = ({ className, style }: DesktopViewProps) => {
|
||||
const containerRef = useRef<HTMLDivElement>(null);
|
||||
const rfbRef = useRef<RFBInstance | null>(null);
|
||||
const isMounted = useMounted();
|
||||
const client = useClient();
|
||||
const [status, setStatus] = useState<'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'error'>(
|
||||
'connecting',
|
||||
);
|
||||
const [errorMsg, setErrorMsg] = useState('');
|
||||
|
||||
useEffect(() => {
|
||||
if (!isMounted) return;
|
||||
const container = containerRef.current;
|
||||
if (!container) return;
|
||||
|
||||
let disposed = false;
|
||||
let attempts = 0;
|
||||
let retryTimer: ReturnType<typeof setTimeout> | null = null;
|
||||
// Tearing an RFB down makes it fire its own `disconnect`, and a bad password fires `securityfailure`
|
||||
// and then `disconnect` too. Both would otherwise be read as "officer went away, reattach".
|
||||
let generation = 0;
|
||||
let fatal = false;
|
||||
const MAX_ATTEMPTS = 5;
|
||||
const RETRY_DELAYS = [1000, 2000, 3000, 5000, 5000];
|
||||
|
||||
const detach = () => {
|
||||
const rfb = rfbRef.current;
|
||||
rfbRef.current = null;
|
||||
generation++;
|
||||
if (!rfb) return;
|
||||
try {
|
||||
rfb.disconnect();
|
||||
} catch {
|
||||
/* ignore */
|
||||
}
|
||||
};
|
||||
|
||||
// x11vnc mirrors :0 with `-forever`, so the desktop itself outlives this socket — losing it means
|
||||
// officer restarted under us, not that the session ended. Reattach instead of parking on
|
||||
// "Disconnected" until someone reopens the panel.
|
||||
const retry = (reason: string) => {
|
||||
if (disposed || fatal || retryTimer) return;
|
||||
detach();
|
||||
if (attempts >= MAX_ATTEMPTS) {
|
||||
setStatus('disconnected');
|
||||
setErrorMsg(reason);
|
||||
return;
|
||||
}
|
||||
const delay = RETRY_DELAYS[attempts] ?? 5000;
|
||||
attempts++;
|
||||
setStatus('reconnecting');
|
||||
setErrorMsg(`${reason} — reconnecting (${attempts}/${MAX_ATTEMPTS})...`);
|
||||
retryTimer = setTimeout(() => {
|
||||
retryTimer = null;
|
||||
void connect();
|
||||
}, delay);
|
||||
};
|
||||
|
||||
const connect = async () => {
|
||||
const gen = ++generation;
|
||||
const isCurrent = () => !disposed && gen === generation;
|
||||
let password = '';
|
||||
try {
|
||||
const res = await client.get<{ password: string }>('/desktop/vnc-password');
|
||||
password = res.password;
|
||||
} catch {
|
||||
if (!isCurrent()) return;
|
||||
// Officer being down is the common case here, and it comes back — so this is a retry, not a
|
||||
// dead end. A sidecar that is genuinely missing still ends up at "Disconnected" after five.
|
||||
retry('Failed to fetch VNC password');
|
||||
return;
|
||||
}
|
||||
|
||||
if (!isCurrent()) return;
|
||||
|
||||
let RFB: Awaited<ReturnType<typeof loadRFB>>['default'];
|
||||
try {
|
||||
const mod = await loadRFB();
|
||||
RFB = mod.default;
|
||||
} catch (err) {
|
||||
console.error('[desktop] Failed to load noVNC:', err);
|
||||
if (!isCurrent()) return;
|
||||
fatal = true;
|
||||
setStatus('error');
|
||||
setErrorMsg('Failed to load noVNC library');
|
||||
return;
|
||||
}
|
||||
|
||||
if (!isCurrent()) return;
|
||||
|
||||
const wsUrl = buildWsUrl();
|
||||
const rfb = new RFB(container, wsUrl, {
|
||||
credentials: { password },
|
||||
});
|
||||
|
||||
// The mirror cannot resize — it reflects the physical screen — so resizeSession is off.
|
||||
// scaleViewport STAYS ON, and it is load-bearing: noVNC maps a click as
|
||||
// (clientX - canvasRect.left) / display._scale, and autoscale() is the only thing that sets the
|
||||
// canvas's displayed size and _scale in the same call. Turn it off and _scale is pinned at 1 while
|
||||
// the canvas is displayed at some other size, which doubled every coordinate on 2026-08-01.
|
||||
rfb.resizeSession = false;
|
||||
rfb.scaleViewport = true;
|
||||
rfb.focusOnClick = true;
|
||||
// noVNC hides the browser's own cursor over the canvas and draws the REMOTE cursor in its place.
|
||||
// Until the server sends a cursor shape its image is RFB.cursors.none — so nothing is drawn, the
|
||||
// real cursor is hidden, and the pointer becomes invisible. Pointer coordinates are unaffected
|
||||
// (measured: x 5..1108, y 11..714 against a 1109x715 session — a perfect 1:1 map), which is why
|
||||
// this looked like a desync when it was only ever a visibility problem: the clicks were landing
|
||||
// correctly all along. A dot is better than nothing when the server has not supplied a shape.
|
||||
rfb.showDotCursor = true;
|
||||
rfbRef.current = rfb;
|
||||
|
||||
rfb.addEventListener('connect', () => {
|
||||
if (!isCurrent()) return;
|
||||
attempts = 0;
|
||||
setErrorMsg('');
|
||||
setStatus('connected');
|
||||
});
|
||||
|
||||
// Every disconnect we did not ask for is worth retrying, clean or not: officer closing its side
|
||||
// tidily during a restart still reports `clean`, and the desktop behind it is still there.
|
||||
rfb.addEventListener('disconnect', () => {
|
||||
if (!isCurrent()) return;
|
||||
rfbRef.current = null;
|
||||
retry('Connection lost');
|
||||
});
|
||||
|
||||
rfb.addEventListener('credentialsrequired', () => {
|
||||
rfb.sendCredentials({ password });
|
||||
});
|
||||
|
||||
rfb.addEventListener('securityfailure', (ev: CustomEvent) => {
|
||||
if (!isCurrent()) return;
|
||||
fatal = true;
|
||||
setStatus('error');
|
||||
setErrorMsg(ev.detail.reason || 'Security failure');
|
||||
});
|
||||
};
|
||||
|
||||
// Coming back to the tab after the retries ran out should try once more rather than stay dead.
|
||||
const handleVisibility = () => {
|
||||
if (disposed || fatal || document.visibilityState !== 'visible') return;
|
||||
if (rfbRef.current || retryTimer) return;
|
||||
attempts = 0;
|
||||
setStatus('connecting');
|
||||
void connect();
|
||||
};
|
||||
document.addEventListener('visibilitychange', handleVisibility);
|
||||
|
||||
void connect();
|
||||
|
||||
return () => {
|
||||
disposed = true;
|
||||
document.removeEventListener('visibilitychange', handleVisibility);
|
||||
if (retryTimer) clearTimeout(retryTimer);
|
||||
detach();
|
||||
};
|
||||
}, [isMounted, client]);
|
||||
|
||||
return (
|
||||
<div
|
||||
className={className}
|
||||
style={{ backgroundColor: '#1a1a2e', overflow: 'hidden', position: 'relative', ...style }}
|
||||
>
|
||||
{status === 'connecting' && (
|
||||
<div className="absolute inset-0 flex items-center justify-center text-sm text-muted-foreground">
|
||||
Connecting to desktop...
|
||||
</div>
|
||||
)}
|
||||
{(status === 'reconnecting' || status === 'disconnected' || status === 'error') && (
|
||||
<div className="absolute inset-0 flex items-center justify-center text-sm text-muted-foreground">
|
||||
{errorMsg || 'Disconnected from desktop'}
|
||||
</div>
|
||||
)}
|
||||
<div ref={containerRef} style={{ width: '100%', height: '100%' }} />
|
||||
</div>
|
||||
);
|
||||
};
|
||||
@@ -0,0 +1,3 @@
|
||||
import { DesktopView } from './DesktopView';
|
||||
|
||||
export const DesktopWrapper = () => <DesktopView className="h-full w-full" />;
|
||||
@@ -0,0 +1,9 @@
|
||||
import type { LayoutNode } from 'officerdev';
|
||||
|
||||
// One panel, filling the route. The desktop is a single framebuffer with its own header — there is no
|
||||
// second thing to put beside it, and splitting the pane would only shrink the screen being mirrored.
|
||||
export const defaultLayout: LayoutNode = {
|
||||
type: 'panel',
|
||||
id: 'desktop-root',
|
||||
appType: 'officerdev/desktop',
|
||||
};
|
||||
@@ -0,0 +1,19 @@
|
||||
// `panels.ts`, not `.tsx` — discovery checks for that exact name.
|
||||
import type { AppRegistryMeta } from 'officerdev';
|
||||
import { MonitorSmartphone } from 'lucide-react';
|
||||
import { DesktopWrapper } from './DesktopWrapper';
|
||||
import { DesktopHeader } from './DesktopHeader';
|
||||
|
||||
export const appRegistryMetas: AppRegistryMeta[] = [
|
||||
{
|
||||
key: 'officerdev/desktop',
|
||||
name: 'Remote Desktop',
|
||||
icon: MonitorSmartphone,
|
||||
component: DesktopWrapper,
|
||||
header: DesktopHeader,
|
||||
availableOnPanel: false,
|
||||
// noVNC scales the remote framebuffer itself and maps pointer coordinates against that; a wrapping
|
||||
// CSS transform would leave every click landing somewhere other than where it was aimed.
|
||||
zoomable: false,
|
||||
},
|
||||
];
|
||||
Reference in New Issue
Block a user