ai-remote 0.1.0 → 0.3.0

package/src/cli/viewer.ts

@@ -0,0 +1,269 @@
+/**
+ * The window a human watches the session through.
+ *
+ * The session already exists and already holds the pixels; this is an
+ * attachment to it. Viewers may come and go, and there may be none at all --
+ * a viewer that could end a session would make supervision a dependency
+ * rather than a feature.
+ *
+ * A viewer that has just attached needs the whole desktop, not a delta, which
+ * is exactly what the framebuffer is for: it sends one keyframe on connect and
+ * painted rectangles after that.
+ */
+
+import { createServer } from 'node:http';
+import type net from 'node:net';
+import { randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { deflateSync } from 'node:zlib';
+import type { RdpSession } from './session';
+import type { Shell } from './shell';
+import { accept, type WebSocketPeer } from './wsserver';
+import { PAGE } from './viewer-page';
+
+export interface Viewer {
+  url: string;
+  /** Resolves when a browser has actually attached. */
+  opened: Promise<void>;
+  /** Pop the window again, for a viewer that was closed by hand. */
+  launch(): void;
+  close(): void;
+}
+
+/**
+ * Frame layout, little-endian:
+ *   u8  kind   1 = keyframe, 2 = rectangle
+ *   u16 left, u16 top, u16 width, u16 height
+ *   deflated RGBA
+ */
+function encodeRect(kind: number, left: number, top: number, width: number, height: number, rgba: Uint8Array): Buffer {
+  const header = Buffer.alloc(9);
+  header.writeUInt8(kind, 0);
+  header.writeUInt16LE(left, 1);
+  header.writeUInt16LE(top, 3);
+  header.writeUInt16LE(width, 5);
+  header.writeUInt16LE(height, 7);
+  return Buffer.concat([header, deflateSync(rgba, { level: 1 })]);
+}
+
+export async function startViewer(
+  session: RdpSession,
+  port: number,
+  { launch = true, openShell }: { launch?: boolean; openShell?: () => Promise<Shell> } = {}
+): Promise<Viewer> {
+  const token = randomBytes(16).toString('hex');
+  const peers = new Set<WebSocketPeer>();
+
+  /**
+   * Which viewers may send input.
+   *
+   * The gate lives here rather than in the page, because a gate in the page is
+   * not a gate: anything that can open a socket can skip it. A viewer attaches
+   * as an observer and has to ask for control, which is also the right default
+   * when the session was opened by an agent -- the human watches first.
+   */
+  const drivers = new WeakSet<WebSocketPeer>();
+
+  /** Undoes each viewer's subscription to shell output when it goes away. */
+  const detachShell = new Map<WebSocketPeer, () => void>();
+
+  /**
+   * Attach a viewer to the terminal, opening it if this is the first ask.
+   *
+   * The scrollback goes out first, so a viewer that opens the terminal ten
+   * minutes into a session sees what has already been run rather than an empty
+   * pane that looks broken.
+   */
+  async function attachShell(peer: WebSocketPeer): Promise<void> {
+    if (!openShell) {
+      peer.send(JSON.stringify({ type: 'shell-error', message: 'This session was started without a terminal. Restart it with --ssh-user NAME.' }));
+      return;
+    }
+    if (detachShell.has(peer)) return;
+
+    peer.send(JSON.stringify({ type: 'shell-status', state: 'opening' }));
+    let shell: Shell;
+    try {
+      shell = await openShell();
+    } catch (error) {
+      peer.send(JSON.stringify({
+        type: 'shell-error',
+        message: error instanceof Error ? error.message : String(error),
+      }));
+      return;
+    }
+
+    const history = shell.scrollback;
+    if (history.length) {
+      peer.send(JSON.stringify({ type: 'shell-data', base64: Buffer.from(history).toString('base64') }));
+    }
+    peer.send(JSON.stringify({ type: 'shell-status', state: 'open' }));
+
+    detachShell.set(peer, shell.onData((bytes) => {
+      peer.send(JSON.stringify({ type: 'shell-data', base64: Buffer.from(bytes).toString('base64') }));
+    }));
+
+    shellFor.set(peer, shell);
+  }
+
+  const shellFor = new Map<WebSocketPeer, Shell>();
+
+  let resolveOpened: () => void;
+  const opened = new Promise<void>((resolve) => { resolveOpened = resolve; });
+
+  const server = createServer((request, response) => {
+    const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+    if (url.pathname === '/' && url.searchParams.get('t') === token) {
+      response.writeHead(200, {
+        'Content-Type': 'text/html; charset=utf-8',
+        'Cache-Control': 'no-store',
+      });
+      response.end(PAGE);
+      return;
+    }
+    response.writeHead(404, { 'Content-Type': 'text/plain' });
+    response.end('Not found');
+  });
+
+  server.on('upgrade', (request, socket) => {
+    const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+    if (url.searchParams.get('t') !== token) { socket.destroy(); return; }
+
+    // Node types an upgrade socket as Duplex; every runtime it has is a
+    // net.Socket, which is what lets the peer turn Nagle off.
+    const peer = accept(request, socket as net.Socket);
+    if (!peer) return;
+    peers.add(peer);
+    resolveOpened();
+
+    const { width, height } = session.framebuffer;
+    peer.send(JSON.stringify({ type: 'hello', width, height, host: session.options.host }));
+    if (width && height) {
+      peer.send(encodeRect(1, 0, 0, width, height, session.framebuffer.pixels));
+    }
+
+    peer.addEventListener('message', (event: Event) => {
+      const raw = (event as MessageEvent).data as string;
+      if (process.env.REMOTECTL_DEBUG) console.log('[viewer] <-', raw);
+      try {
+        const message = JSON.parse(raw);
+
+        if (message.type === 'control') {
+          if (message.on) drivers.add(peer); else drivers.delete(peer);
+          peer.send(JSON.stringify({ type: 'control', on: Boolean(message.on) }));
+          return;
+        }
+
+        if (message.type === 'shell-attach') { void attachShell(peer); return; }
+
+        if (!drivers.has(peer)) return;
+
+        if (message.type === 'shell-input') {
+          shellFor.get(peer)?.write(String(message.text ?? ''));
+          return;
+        }
+        if (message.type === 'shell-resize') {
+          shellFor.get(peer)?.resize(Number(message.columns) || 120, Number(message.rows) || 30);
+          return;
+        }
+
+        applyInput(session, message);
+      } catch (error) {
+        // A malformed frame from a viewer must never take the session down.
+        console.warn('[viewer] dropped an unreadable message', error);
+      }
+    });
+    peer.addEventListener('close', () => {
+      peers.delete(peer);
+      detachShell.get(peer)?.();
+      detachShell.delete(peer);
+    });
+  });
+
+  /**
+   * Loopback only. The viewer carries a live desktop and takes input for it.
+   *
+   * A busy port is not a reason to fail: a second session, or a stale process
+   * holding the default, would otherwise take the whole connection down. The
+   * chosen port is reported back, so nothing has to guess which one it got.
+   */
+  const bound = await new Promise<number>((resolve, reject) => {
+    const listen = (candidate: number, retry: boolean) => {
+      server.once('error', (error: NodeJS.ErrnoException) => {
+        if (retry && error.code === 'EADDRINUSE') { listen(0, false); return; }
+        reject(error);
+      });
+      server.listen(candidate, '127.0.0.1', () => {
+        const address = server.address();
+        resolve(typeof address === 'object' && address ? address.port : candidate);
+      });
+    };
+    listen(port, true);
+  });
+
+  session.onResize((width, height) => {
+    for (const peer of peers) {
+      peer.send(JSON.stringify({ type: 'resize', width, height }));
+      peer.send(encodeRect(1, 0, 0, width, height, session.framebuffer.pixels));
+    }
+  });
+
+  session.onPaint((rects) => {
+    if (!peers.size) return;
+    for (const rect of rects) {
+      const payload = encodeRect(2, rect.left, rect.top, rect.width, rect.height, rect.rgba);
+      for (const peer of peers) peer.send(payload);
+    }
+  });
+
+  const url = `http://127.0.0.1:${bound}/?t=${token}`;
+  if (launch) open(url);
+
+  return {
+    url,
+    opened,
+    launch() { open(url); },
+    close() {
+      for (const peer of peers) peer.close();
+      server.close();
+    },
+  };
+}
+
+function applyInput(session: RdpSession, message: any): void {
+  switch (message.type) {
+    case 'move':
+      session.movePointer(message.x, message.y);
+      break;
+    case 'button':
+      session.pointerButton(message.x, message.y, message.button ?? 0, Boolean(message.pressed));
+      break;
+    case 'scroll':
+      session.scroll(message.x, message.y, message.dx ?? 0, message.dy ?? 0);
+      break;
+    case 'key':
+      session.sendKeyCode(message.code, Boolean(message.pressed));
+      break;
+    case 'text':
+      session.typeText(String(message.text ?? ''));
+      break;
+    case 'cad':
+      session.sendCtrlAltDel();
+      break;
+    default:
+      break;
+  }
+}
+
+/** Pop the window. A failure here is not a failure of the session. */
+function open(url: string): void {
+  const command = process.platform === 'darwin' ? 'open'
+    : process.platform === 'win32' ? 'cmd'
+    : 'xdg-open';
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  try {
+    spawn(command, args, { stdio: 'ignore', detached: true }).unref();
+  } catch {
+    // Headless, or no browser. The URL was printed; that is enough.
+  }
+}

package/src/cli/wsserver.ts

@@ -0,0 +1,144 @@
+/**
+ * Just enough WebSocket to talk to a browser tab.
+ *
+ * Node has no WebSocket server, and pulling one in would cost `npx remotectl`
+ * its single-download start. What the viewer needs is small: an upgrade
+ * handshake, binary frames out, text frames in.
+ */
+
+import { createHash } from 'node:crypto';
+import type { IncomingMessage } from 'node:http';
+import type net from 'node:net';
+
+const GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+
+export class WebSocketPeer extends EventTarget {
+  #socket: net.Socket;
+  #buffer = Buffer.alloc(0);
+  /** Stop writing. Set as soon as closing begins, from either end. */
+  #closed = false;
+  /**
+   * Whether the close event has gone out.
+   *
+   * Kept apart from #closed on purpose: one flag doing both jobs meant a peer
+   * that closed itself -- which is what a browser tab does when it goes away --
+   * swallowed its own close event, and the session went on sending frames to a
+   * viewer that had left.
+   */
+  #reported = false;
+
+  constructor(socket: net.Socket) {
+    super();
+    this.#socket = socket;
+    socket.on('data', (chunk: Buffer) => this.#onData(chunk));
+    socket.on('close', () => this.#onClose());
+    socket.on('error', () => this.#onClose());
+  }
+
+  get closed(): boolean { return this.#closed; }
+
+  send(data: string | Uint8Array): void {
+    if (this.#closed) return;
+    const isText = typeof data === 'string';
+    const payload = isText ? Buffer.from(data, 'utf8') : Buffer.from(data);
+    this.#socket.write(frame(isText ? 0x1 : 0x2, payload));
+  }
+
+  close(): void {
+    if (!this.#closed) {
+      this.#closed = true;
+      try { this.#socket.end(frame(0x8, Buffer.alloc(0))); } catch { /* already gone */ }
+    }
+    this.#onClose();
+  }
+
+  #onClose(): void {
+    this.#closed = true;
+    if (this.#reported) return;
+    this.#reported = true;
+    this.dispatchEvent(new Event('close'));
+  }
+
+  #onData(chunk: Buffer): void {
+    if (process.env.REMOTECTL_DEBUG) console.log('[ws] data', chunk.length, 'bytes');
+    this.#buffer = Buffer.concat([this.#buffer, chunk]);
+
+    for (;;) {
+      const parsed = readFrame(this.#buffer);
+      if (!parsed) return;
+      this.#buffer = parsed.rest;
+
+      if (parsed.opcode === 0x8) { this.close(); return; }
+      if (parsed.opcode === 0x9) { this.#socket.write(frame(0xa, parsed.payload)); continue; }
+      if (parsed.opcode === 0x1) {
+        this.dispatchEvent(new MessageEvent('message', { data: parsed.payload.toString('utf8') }));
+      }
+    }
+  }
+}
+
+/** Server frames are never masked, and the viewer sends nothing large. */
+function frame(opcode: number, payload: Buffer): Buffer {
+  const length = payload.length;
+  let header: Buffer;
+
+  if (length < 126) {
+    header = Buffer.from([0x80 | opcode, length]);
+  } else if (length < 65536) {
+    header = Buffer.alloc(4);
+    header[0] = 0x80 | opcode;
+    header[1] = 126;
+    header.writeUInt16BE(length, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = 0x80 | opcode;
+    header[1] = 127;
+    header.writeBigUInt64BE(BigInt(length), 2);
+  }
+
+  return Buffer.concat([header, payload]);
+}
+
+function readFrame(buffer: Buffer) {
+  if (buffer.length < 2) return null;
+
+  const opcode = buffer[0] & 0x0f;
+  const masked = (buffer[1] & 0x80) !== 0;
+  let length = buffer[1] & 0x7f;
+  let offset = 2;
+
+  if (length === 126) {
+    if (buffer.length < 4) return null;
+    length = buffer.readUInt16BE(2);
+    offset = 4;
+  } else if (length === 127) {
+    if (buffer.length < 10) return null;
+    length = Number(buffer.readBigUInt64BE(2));
+    offset = 10;
+  }
+
+  const maskKey = masked ? buffer.subarray(offset, offset + 4) : null;
+  if (masked) offset += 4;
+  if (buffer.length < offset + length) return null;
+
+  const payload = Buffer.from(buffer.subarray(offset, offset + length));
+  if (maskKey) for (let i = 0; i < payload.length; i++) payload[i] ^= maskKey[i % 4];
+
+  return { opcode, payload, rest: buffer.subarray(offset + length) };
+}
+
+/** Complete the HTTP upgrade a browser sends, and hand back the peer. */
+export function accept(request: IncomingMessage, socket: net.Socket): WebSocketPeer | null {
+  const key = request.headers['sec-websocket-key'];
+  if (typeof key !== 'string') { socket.destroy(); return null; }
+
+  const acceptKey = createHash('sha1').update(key + GUID).digest('base64');
+  socket.write(
+    'HTTP/1.1 101 Switching Protocols\r\n'
+    + 'Upgrade: websocket\r\n'
+    + 'Connection: Upgrade\r\n'
+    + `Sec-WebSocket-Accept: ${acceptKey}\r\n\r\n`
+  );
+  socket.setNoDelay(true);
+  return new WebSocketPeer(socket);
+}

package/src/protocols/rdp/client.ts

@@ -150,6 +150,8 @@ export class RdpClient extends EventTarget {
       keyboardLayout: 0x409,
       clientName: 'cf-gateway',
       security: 'auto',
+      /** Returns a WebSocket-shaped transport for `url`; default is a real one. */
+      openTransport: null,
       clipboard: true,
       remoteApp: null,
       performance: PERF_DISABLE_WALLPAPER | PERF_DISABLE_FULLWINDOWDRAG | PERF_DISABLE_MENUANIMATIONS,
@@ -231,7 +233,13 @@ export class RdpClient extends EventTarget {
     this.remoteAppFitTimer = null;
     this.remoteAppCloseTimer = null;
 
-    this.socket = new WebSocket(this.url);
+    // The transport is injected so this client can run anywhere. In a browser
+    // it is a WebSocket to the gateway's relay; in the CLI it is a TCP socket
+    // straight at the host. Everything above it -- X.224, TLS, CredSSP, MCS --
+    // is the same either way, which is the whole reason it is a seam.
+    this.socket = this.options.openTransport
+      ? this.options.openTransport(this.url)
+      : new WebSocket(this.url);
     this.socket.binaryType = 'arraybuffer';
     this.socket.addEventListener('open', () => this.#onOpen());
     this.socket.addEventListener('message', (event) => this.#onMessage(event));

package/src/protocols/ssh/session.ts

@@ -255,6 +255,7 @@ export class SshSession extends EventTarget {
 
     this.transport = new SshTransport(url, {
       verifyHost: options.verifyHost || (async () => true),
+      openTransport: options.openTransport || null,
       log: (step: number, detail) => console.info(`[SSH] ${step}`, detail),
     });
 

package/src/protocols/ssh/transport.ts

@@ -87,6 +87,7 @@ export class SshTransport extends EventTarget {
   verifyHost: (info: any) => Promise<boolean> | boolean;
   log: (...args: any[]) => void;
   socket: WebSocket | null;
+  openTransport: ((url: string) => any) | null;
   closed: boolean;
   buffer: Uint8Array;
   serverVersion: string;
@@ -113,12 +114,21 @@ export class SshTransport extends EventTarget {
    * @param {(info: object) => Promise<boolean>} options.verifyHost decides
    *   whether an unknown or changed host key may be used.
    */
-  constructor(url: string, { verifyHost, log }: { verifyHost?: (info: any) => Promise<boolean> | boolean; log?: (...args: any[]) => void } = {}) {
+  constructor(
+    url: string,
+    { verifyHost, log, openTransport }: {
+      verifyHost?: (info: any) => Promise<boolean> | boolean;
+      log?: (...args: any[]) => void;
+      /** Returns a WebSocket-shaped transport for `url`; default is a real one. */
+      openTransport?: ((url: string) => any) | null;
+    } = {}
+  ) {
     super();
 
     this.url = url;
     this.verifyHost = verifyHost || (() => true);
     this.log = log || (() => {});
+    this.openTransport = openTransport || null;
 
     this.socket = null;
     this.closed = false;
@@ -142,7 +152,10 @@ export class SshTransport extends EventTarget {
   // --- connection ----------------------------------------------------------
 
   connect() {
-    this.socket = new WebSocket(this.url);
+    // Injected so this client can run anywhere: a WebSocket to the gateway in
+    // a browser, a TCP socket straight at the host in the CLI. The key
+    // exchange and everything above it is identical either way.
+    this.socket = this.openTransport ? this.openTransport(this.url) : new WebSocket(this.url);
     this.socket.binaryType = 'arraybuffer';
 
     this.socket.addEventListener('open', () => {