officerdev/platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

a plugin can serve a websocket

Browse Source 
Bun's route table is fixed at serve() and WS_ROUTES is read once before it, so a
plugin installed afterwards could never add a socket route. That was a hard
ceiling, not a preference: /minesweeper had to live in the platform and
plugins/desktop could not stream a display at all.

The way out was already in the tree and had one consumer. dev-proxy serves a socket
with no WS_ROUTES entry, through a WILDCARD route whose handler calls
server.upgrade itself. Nothing has to become dynamic, because a plugin name is a
path segment rather than a route — one wildcard declared at boot serves every
plugin that will ever be installed.

Authorisation is the PLUGIN's own capability, asked as if the socket were a GET
against its HTTP prefix. That is the safety argument: there is no second permission
to grant, forget, or drift, so granting a plugin grants its socket and revoking it
closes it. It is also why plugin-ws is exempt from the boot totality check rather
than carrying a registry entry — one entry covering every plugin's socket would
mean granting one plugin granted them all.

A target is a TCP address and never a URL, which keeps the relay ignorant of what
it carries. That ignorance is the only reason one relay can serve an RFB display
and a line-oriented sidecar. Loopback only and not configurable: a plugin naming an
arbitrary host would be a request-forgery primitive handed to every plugin author.

sidecarPort() is new because createSidecarProxy learned announced ports per-proxy
and that state was unreachable from anywhere else — a second subscription would
have been a second thing to keep in step.

Verified: boots past the totality gate, and both an existing and a non-existent
plugin refuse 401 before revealing which. NOT yet verified: that it relays a byte.
Minesweeper is about to be the first caller, which is what proves it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043
This commit is contained in:
pastilhas
2026-08-23 15:21:10 +00:00
co-authored by Claude Opus 5
parent 1c435a88ae
commit eba0e86758
6 changed files with 291 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/servers/api/plugin-ws/target.ts
+42
View File
@@ -0,0 +1,42 @@
import { sidecarPort } from '@@/sidecar-registry';
import { snapshotPlugins } from '@@/plugins/mount';
/*
Where a plugin's socket actually goes.
A target is a TCP address and never a URL, and that is what keeps the relay ignorant of the protocol on
the other side. The ignorance is the point: it is the only reason one relay can serve an RFB display and a
line-oriented sidecar without knowing which is which. The moment this returned a scheme or a path, the
relay would have to care what it was carrying.
Two forms, because two things genuinely differ:
{ port: 5900 } a fixed port a plugin's own service listens on — `x11vnc` for a desktop, or
anything the plugin starts itself and knows the number of in advance.
{ sidecar: 'name' } resolved at connect time, because a sidecar binds an EPHEMERAL port and announces
it. A manifest cannot know that number, which is why the indirection exists rather
than being a convenience.
**Host is always loopback and is not configurable.** A plugin socket that could name an arbitrary host
would be a request-forgery primitive handed to every plugin author and reachable by anyone the plugin is
granted to. There is no case for it that a sidecar does not already serve.
*/
export type PluginWsTarget = { host: string; port: number };
export async function pluginWsTargetFor(appName: string): Promise<PluginWsTarget | null> {
const { states } = await snapshotPlugins();
// Installed, not merely present on disk. A plugin directory that exists but is not installed has no
// routes and no permission, so it must have no socket either.
const state = states.find((st) => st.plugin.appName === appName && st.install);
const socket = state?.plugin.manifest.websocket;
if (!socket) return null;
if ('port' in socket) return { host: '127.0.0.1', port: socket.port };
// A sidecar that has not announced its port yet is indistinguishable from one that never will, and both
// are correctly a refusal — there is nothing to relay onto. The caller says "not accepting connections",
// which is true either way.
const port = sidecarPort(socket.sidecar);
return port ? { host: '127.0.0.1', port } : null;
}
src/servers/api/plugin-ws/websocket.ts
+182
View File
@@ -0,0 +1,182 @@
import type { ServerWebSocket, Socket } from 'bun';
import { resolveAuthToken } from '@@/auth-token';
import { isTokenBlacklisted } from 'officerdb';
import { isApiRequestAllowed } from '@@/permissions/authorize';
import { pluginWsTargetFor } from './target';
/*
One websocket door for every plugin, so a plugin can have a socket at all.
── Why this exists ──
Bun's route table is fixed at `serve()`, and `WS_ROUTES` is a static object read at boot. So a plugin
installed afterwards had no way to add a socket route, and "a websocket provider is a platform concern"
became a hard ceiling rather than a preference: `/minesweeper` had to live in the platform and
`plugins/desktop` could not do the same thing at all.
The way out was already in the tree. `dev-proxy` serves a socket without a `WS_ROUTES` entry, through a
WILDCARD route whose handler calls `server.upgrade` itself. Nothing about the route table needs to become
dynamic — one wildcard declared at boot can serve every plugin that will ever be installed, because the
plugin name is a path segment rather than a route.
── What it does and does not read ──
Bytes, both ways, without interpreting them. Same as the terminal's relay onto the pty sidecar and the
minesweeper relay onto x11vnc: frame boundaries carry no meaning to a stream protocol, so chunks are
forwarded exactly as they arrive.
A plugin's target is a TCP address, never a URL. That is deliberate — it keeps this file ignorant of
whatever protocol is on the other side, which is the only reason one relay can serve an RFB display and a
line-oriented sidecar without knowing which is which.
*/
export type PluginWSData = {
provider: 'plugin-ws';
plugin: string;
host: string;
port: number;
userId: number;
};
type Relay = { socket: Socket | null; queue: Uint8Array[]; done: boolean };
const relays = new Map<ServerWebSocket<PluginWSData>, Relay>();
const closeClient = (ws: ServerWebSocket<PluginWSData>, code: number, reason: string) => {
const relay = relays.get(ws);
relays.delete(ws);
if (relay) relay.done = true;
try {
relay?.socket?.end();
} catch {
/* already gone */
}
try {
ws.close(code, reason);
} catch {
/* already closing */
}
};
export const pluginWsWebsocket = {
async open(ws: ServerWebSocket<PluginWSData>) {
/*
The queue is not an optimisation. Bun requires `server.upgrade` to be synchronous, so the client is
already connected and may already be talking by the time `Bun.connect` resolves — and an RFB client
sends its protocol version immediately. Dropping those bytes desynchronises the stream in a way that
looks like a corrupt display rather than a lost packet. Learned by dev-proxy first.
*/
const relay: Relay = { socket: null, queue: [], done: false };
relays.set(ws, relay);
try {
const socket = await Bun.connect({
hostname: ws.data.host,
port: ws.data.port,
socket: {
data: (_s, chunk) => {
try {
ws.send(chunk);
} catch {
/* client gone; the close handler tidies up */
}
},
close: () => closeClient(ws, 1011, 'upstream closed'),
error: () => closeClient(ws, 1011, 'upstream error'),
},
});
// Between the await above and here the client may have gone. Writing to a socket nobody is reading
// would keep the upstream connection open for as long as the plugin's process lives.
if (relay.done) {
socket.end();
return;
}
relay.socket = socket;
for (const chunk of relay.queue) socket.write(chunk);
relay.queue.length = 0;
} catch {
// A plugin whose process is not listening is the ordinary case, not an exception: a sidecar that has
// not booted yet, or a plugin whose service is stopped. The client is told, and told which plugin.
closeClient(ws, 1011, `${ws.data.plugin} is not accepting connections`);
}
},
message(ws: ServerWebSocket<PluginWSData>, message: string | Uint8Array) {
const relay = relays.get(ws);
if (!relay) return;
const bytes = typeof message === 'string' ? new TextEncoder().encode(message) : message;
if (relay.socket) relay.socket.write(bytes);
else relay.queue.push(bytes);
},
close(ws: ServerWebSocket<PluginWSData>) {
const relay = relays.get(ws);
relays.delete(ws);
if (relay) relay.done = true;
try {
relay?.socket?.end();
} catch {
/* already gone */
}
},
};
/**
* `/api/plugin-ws/<plugin>` with an upgrade header.
*
* Authorisation is PER PLUGIN, which is why `plugin-ws` is exempt from the boot-time totality check rather
* than carrying a registry entry of its own. One entry covering every plugin's socket would be a hole:
* granting one plugin would grant them all.
*
* So the decision is delegated to the plugin's OWN capability, by asking the same question its HTTP routes
* are asked — `isApiRequestAllowed(user, 'GET', '/api/<plugin>')`. That is deliberate and it is the whole
* safety argument: there is no second permission to grant, to forget, or to drift out of step. Granting a
* plugin grants its socket, and revoking it closes it.
*
* Async, like `upgradeWs`. `server.upgrade` must be called synchronously with respect to the request, but
* Bun accepts a route handler that returns a promise — which is what lets the token resolve, the blacklist
* check and the permission decision all happen before anything is upgraded.
*/
export async function upgradePluginWs(req: Request, server: any): Promise<Response | undefined> {
const url = new URL(req.url);
const match = url.pathname.match(/^\/api\/plugin-ws\/([a-z0-9-]{1,64})\/?$/);
if (!match) return undefined;
const plugin = match[1]!;
// A browser cannot set headers on a WebSocket upgrade, so the token arrives as a query parameter — the
// concession every other socket here already makes. Verified through the same resolver as the HTTP doors,
// so an API key that works against /api works here too.
const token = url.searchParams.get('token');
if (!token) return new Response('Unauthorized', { status: 401 });
try {
const user = await resolveAuthToken(token);
if (!user) return new Response('Unauthorized', { status: 401 });
if (user.jti && (await isTokenBlacklisted(user.jti))) return new Response('Unauthorized', { status: 401 });
// The plugin's own gate, asked as if this were a GET against its HTTP prefix.
if (!(await isApiRequestAllowed(user.id, 'GET', `/api/${plugin}`)).allowed) {
return new Response('Forbidden', { status: 403 });
}
const target = await pluginWsTargetFor(plugin);
// 404 for both "no such plugin" and "no socket declared", identically. A caller must not be able to
// discover which plugins are installed by which refusal it gets — the same reasoning as SendOff's
// recipient lookup.
if (!target) return new Response('Not found', { status: 404 });
const ok = server.upgrade(req, {
data: {
provider: 'plugin-ws',
plugin,
host: target.host,
port: target.port,
userId: user.id,
} satisfies PluginWSData,
});
return ok ? undefined : new Response('Upgrade failed', { status: 400 });
} catch {
// Any failure to establish WHO is calling denies. Never open a socket on a maybe.
return new Response('Unauthorized', { status: 401 });
}
}