ai-remote 0.1.0

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * The vocabulary every host of this stack shares.
+ *
+ * Deliberately no protocol engines: a Worker that only needs to know what a
+ * host roster is should not pull noVNC or an RDP state machine into its
+ * bundle. The engines live behind `@remotectl/core/protocols`.
+ */
+
+export * from './shared/connection';
+export * from './shared/device';
+export * from './shared/hosts';
+export * from './shared/icons';
+export * from './shared/protocol';
+export * from './shared/signals';

package/src/protocols/index.ts

@@ -0,0 +1,72 @@
+/**
+ * The protocol registry the workspace talks to.
+ *
+ * The UI owns the toolbar, the dialogs, the stats rail and the on-screen
+ * keyboard, none of which care whether a session is VNC or RDP. Everything that
+ * does differ -- the endpoint, how a client is constructed, the wording of a
+ * failure, the labels in the connect dialog -- is looked up here instead of
+ * branching at each site.
+ */
+
+import { rdpDriver } from './rdp/session';
+import { vncDriver } from './vnc/session';
+import type { DisconnectContext, ProtocolDriver } from './types';
+import type { RemoteProtocol } from '../shared/protocol';
+
+export type { ProtocolDriver, RemoteSession, SessionOptions, ScreenGeometry } from './types';
+
+export const DRIVERS: Record<RemoteProtocol, ProtocolDriver> = {
+  vnc: vncDriver,
+  rdp: rdpDriver,
+};
+
+/** Unknown names fall back to VNC, which is what the dialog opens on. */
+export function driverFor(protocol: string | undefined): ProtocolDriver {
+  return DRIVERS[protocol as RemoteProtocol] ?? DRIVERS.vnc;
+}
+
+/** What the workspace knows about a session that has just ended. */
+export interface DisconnectDiagnostic {
+  protocol: RemoteProtocol;
+  /** The transport close, when one arrived. A 1006 means it did not. */
+  close: { code: number; reason: string } | null;
+  /** True once the session had reached the desktop. */
+  established: boolean;
+}
+
+/**
+ * Explain a disconnect in terms someone can act on. The protocol gets first
+ * say, then the close codes that mean the same thing either way.
+ */
+export function explainDisconnect(
+  diagnostic: DisconnectDiagnostic,
+  clean: boolean,
+  protocolMessage: string
+): string {
+  // A client that reports its own failure states it in the protocol's terms,
+  // which is always more specific than anything the transport can say.
+  if (protocolMessage) return protocolMessage;
+
+  const code = diagnostic.close?.code;
+  const reason = diagnostic.close?.reason.trim() ?? '';
+  const suffix = code ? ` (WebSocket ${code}${reason ? `: ${reason}` : ''})` : '';
+  const context: DisconnectContext = { ...(code === undefined ? {} : { code }), reason, suffix };
+
+  const driver = driverFor(diagnostic.protocol);
+  const specific = driver.describeDisconnect(context);
+  if (specific) return specific;
+
+  const name = driver.protocol.toUpperCase();
+  if (/tcp (reached )?eof/i.test(reason)) {
+    return `The ${name} host accepted the connection and then closed it${suffix}. `
+      + 'Check its remote-access permissions and the account name.';
+  }
+  if (code === 1006) {
+    return 'The connection was interrupted before a close reason arrived (WebSocket 1006). '
+      + 'This can happen during a deployment or a brief network change. Automatic reconnect '
+      + 'did not restore the session; reconnect once, then check Worker live logs if it repeats.';
+  }
+  if (reason) return `The remote session ended${suffix}.`;
+  if (clean) return `The remote server closed the session cleanly${suffix || ' (no reason supplied)'}.`;
+  return `The ${name} negotiation failed${suffix || ' before the server supplied a close reason'}.`;
+}

package/src/protocols/rdp/buffer.ts

@@ -0,0 +1,204 @@
+// Binary reader/writer used by every RDP layer. RDP mixes endianness freely --
+// TPKT and MCS are big endian, everything above them is little endian -- so the
+// byte order is part of each call rather than a mode on the object.
+
+/**
+ * Plain `Uint8Array` throughout. Pinning the buffer type parameter would be
+ * more precise, but every layer above this one passes byte slices around and
+ * the variance between `ArrayBuffer` and `ArrayBufferLike` then has to be
+ * restated at each boundary for no benefit the protocol code can use.
+ */
+function allocate(length: number): Uint8Array {
+  return new Uint8Array(length);
+}
+
+export class Writer {
+  private bytes: Uint8Array;
+  private view: DataView;
+  private offset = 0;
+
+  constructor(capacity = 512) {
+    this.bytes = allocate(capacity);
+    this.view = new DataView(this.bytes.buffer);
+  }
+
+  #ensure(extra: number): void {
+    if (this.offset + extra <= this.bytes.length) return;
+    let capacity = this.bytes.length * 2;
+    while (capacity < this.offset + extra) capacity *= 2;
+    const grown = allocate(capacity);
+    grown.set(this.bytes.subarray(0, this.offset));
+    this.bytes = grown;
+    this.view = new DataView(grown.buffer);
+  }
+
+  u8(value: number): this {
+    this.#ensure(1);
+    this.view.setUint8(this.offset, value);
+    this.offset += 1;
+    return this;
+  }
+
+  u16le(value: number): this {
+    this.#ensure(2);
+    this.view.setUint16(this.offset, value, true);
+    this.offset += 2;
+    return this;
+  }
+
+  u16be(value: number): this {
+    this.#ensure(2);
+    this.view.setUint16(this.offset, value, false);
+    this.offset += 2;
+    return this;
+  }
+
+  u32le(value: number): this {
+    this.#ensure(4);
+    this.view.setUint32(this.offset, value >>> 0, true);
+    this.offset += 4;
+    return this;
+  }
+
+  u32be(value: number): this {
+    this.#ensure(4);
+    this.view.setUint32(this.offset, value >>> 0, false);
+    this.offset += 4;
+    return this;
+  }
+
+  raw(bytes: Uint8Array): this {
+    this.#ensure(bytes.length);
+    this.bytes.set(bytes, this.offset);
+    this.offset += bytes.length;
+    return this;
+  }
+
+  zeros(count: number): this {
+    this.#ensure(count);
+    this.offset += count;
+    return this;
+  }
+
+  /** UTF-16LE, optionally padded or truncated to a fixed byte width. */
+  utf16le(text: string, fixedBytes?: number): this {
+    const start = this.offset;
+    for (const unit of text) {
+      const code = unit.codePointAt(0) ?? 0;
+      // Fixed-width fields must keep room for the terminating NUL.
+      if (fixedBytes !== undefined && this.offset - start >= fixedBytes - 2) break;
+      if (code > 0xffff) {
+        // Surrogate pair: both halves are already what UTF-16 needs.
+        for (let i = 0; i < unit.length; i++) this.u16le(unit.charCodeAt(i));
+      } else {
+        this.u16le(code);
+      }
+    }
+    if (fixedBytes !== undefined) {
+      this.zeros(fixedBytes - (this.offset - start));
+    }
+    return this;
+  }
+
+  /** Overwrite an earlier 16-bit slot, for length fields known only later. */
+  patchU16le(position: number, value: number): this {
+    this.view.setUint16(position, value, true);
+    return this;
+  }
+
+  patchU16be(position: number, value: number): this {
+    this.view.setUint16(position, value, false);
+    return this;
+  }
+
+  get length(): number {
+    return this.offset;
+  }
+
+  take(): Uint8Array {
+    return this.bytes.slice(0, this.offset);
+  }
+}
+
+export class Reader {
+  private readonly bytes: Uint8Array;
+  private readonly view: DataView;
+  offset: number;
+
+  constructor(bytes: Uint8Array, offset = 0) {
+    this.bytes = bytes;
+    this.view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    this.offset = offset;
+  }
+
+  get remaining(): number {
+    return this.bytes.length - this.offset;
+  }
+
+  #need(count: number): void {
+    if (this.remaining < count) {
+      throw new Error(`RDP: truncated frame (needed ${count} bytes, ${this.remaining} left)`);
+    }
+  }
+
+  u8(): number {
+    this.#need(1);
+    return this.view.getUint8(this.offset++);
+  }
+
+  u16le(): number {
+    this.#need(2);
+    const value = this.view.getUint16(this.offset, true);
+    this.offset += 2;
+    return value;
+  }
+
+  u16be(): number {
+    this.#need(2);
+    const value = this.view.getUint16(this.offset, false);
+    this.offset += 2;
+    return value;
+  }
+
+  u32le(): number {
+    this.#need(4);
+    const value = this.view.getUint32(this.offset, true);
+    this.offset += 4;
+    return value;
+  }
+
+  u32be(): number {
+    this.#need(4);
+    const value = this.view.getUint32(this.offset, false);
+    this.offset += 4;
+    return value;
+  }
+
+  raw(count: number): Uint8Array {
+    this.#need(count);
+    const slice = this.bytes.subarray(this.offset, this.offset + count);
+    this.offset += count;
+    return slice;
+  }
+
+  skip(count: number): this {
+    this.#need(count);
+    this.offset += count;
+    return this;
+  }
+
+  rest(): Uint8Array {
+    return this.bytes.subarray(this.offset);
+  }
+}
+
+export function concatBytes(...parts: readonly Uint8Array[]): Uint8Array {
+  const total = parts.reduce((sum, part) => sum + part.length, 0);
+  const out = allocate(total);
+  let offset = 0;
+  for (const part of parts) {
+    out.set(part, offset);
+    offset += part.length;
+  }
+  return out;
+}

package/src/protocols/rdp/caps.ts

@@ -0,0 +1,304 @@
+// Capability exchange (MS-RDPBCGR 2.2.7).
+//
+// This client deliberately advertises no drawing-order support and no bitmap
+// cache, which makes the host fall back to plain bitmap updates for the whole
+// screen. That is the one output path a from-scratch client can implement
+// correctly, and it is what keeps the rest of this module small.
+
+import { Reader, Writer, concatBytes } from './buffer';
+
+export const CAPSET = {
+  GENERAL: 1,
+  BITMAP: 2,
+  ORDER: 3,
+  BITMAPCACHE: 4,
+  CONTROL: 5,
+  ACTIVATION: 7,
+  POINTER: 8,
+  SHARE: 9,
+  COLORCACHE: 10,
+  SOUND: 12,
+  INPUT: 13,
+  FONT: 14,
+  BRUSH: 15,
+  GLYPHCACHE: 16,
+  OFFSCREENCACHE: 17,
+  VIRTUALCHANNEL: 20,
+  RAIL: 23,
+  WINDOW: 24,
+  MULTIFRAGMENTUPDATE: 26,
+  LARGE_POINTER: 27,
+  SURFACE_COMMANDS: 28,
+  BITMAP_CODECS: 29,
+};
+
+const INPUT_FLAG_SCANCODES = 0x0001;
+const INPUT_FLAG_MOUSEX = 0x0004;
+const INPUT_FLAG_UNICODE = 0x0010;
+
+const FASTPATH_OUTPUT_SUPPORTED = 0x0001;
+const LONG_CREDENTIALS_SUPPORTED = 0x0004;
+const NEGOTIATE_ORDER_SUPPORT = 0x0002;
+const ZERO_BOUNDS_DELTA_SUPPORT = 0x0008;
+
+function capabilitySet(type: number, body: Uint8Array) {
+  const writer = new Writer(body.length + 4);
+  writer.u16le(type).u16le(body.length + 4).raw(body);
+  return writer.take();
+}
+
+function generalCapability() {
+  const writer = new Writer(24);
+  writer.u16le(1);                            // osMajorType: Windows
+  writer.u16le(3);                            // osMinorType: Windows NT
+  writer.u16le(0x0200);                       // protocolVersion
+  writer.u16le(0);                            // pad
+  writer.u16le(0);                            // generalCompressionTypes
+  // Fast-path output has to be advertised. Windows 8 and later send graphics
+  // only on the fast path, so a client that asks for the slow path alone gets a
+  // clean session that never paints anything.
+  writer.u16le(FASTPATH_OUTPUT_SUPPORTED | LONG_CREDENTIALS_SUPPORTED); // extraFlags
+  writer.u16le(0);                            // updateCapabilityFlag
+  writer.u16le(0);                            // remoteUnshareFlag
+  writer.u16le(0);                            // generalCompressionLevel
+  // Both are declarations that the client may SEND these PDUs. The initial
+  // full-screen paint depends on it: a host that thinks the client cannot ask
+  // for a refresh has no reason to honour the request.
+  writer.u8(1);                               // refreshRectSupport
+  writer.u8(1);                               // suppressOutputSupport
+  return capabilitySet(CAPSET.GENERAL, writer.take());
+}
+
+function bitmapCapability(width: number, height: number) {
+  const writer = new Writer(28);
+  writer.u16le(16);      // preferredBitsPerPixel
+  writer.u16le(1);       // receive1BitPerPixel
+  writer.u16le(1);       // receive4BitsPerPixel
+  writer.u16le(1);       // receive8BitsPerPixel
+  writer.u16le(width);
+  writer.u16le(height);
+  writer.u16le(0);       // pad
+  writer.u16le(1);       // desktopResizeFlag
+  writer.u16le(1);       // bitmapCompressionFlag
+  writer.u8(0);          // highColorFlags
+  writer.u8(0);          // drawingFlags
+  writer.u16le(1);       // multipleRectangleSupport
+  writer.u16le(0);       // pad
+  return capabilitySet(CAPSET.BITMAP, writer.take());
+}
+
+function orderCapability() {
+  const writer = new Writer(88);
+  writer.zeros(16);                                             // terminalDescriptor
+  writer.u32le(0);                                              // pad
+  writer.u16le(1);                                              // desktopSaveXGranularity
+  writer.u16le(20);                                             // desktopSaveYGranularity
+  writer.u16le(0);                                              // pad
+  writer.u16le(1);                                              // maximumOrderLevel
+  writer.u16le(0);                                              // numberFonts
+  writer.u16le(NEGOTIATE_ORDER_SUPPORT | ZERO_BOUNDS_DELTA_SUPPORT);
+  writer.zeros(32);                                             // orderSupport: none
+  writer.u16le(0);                                              // textFlags
+  writer.u16le(0);                                              // orderSupportExFlags
+  writer.u32le(0);                                              // pad
+  writer.u32le(230400);                                         // desktopSaveSize
+  writer.u16le(0);                                              // pad
+  writer.u16le(0);                                              // pad
+  writer.u16le(0);                                              // textANSICodePage
+  writer.u16le(0);                                              // pad
+  return capabilitySet(CAPSET.ORDER, writer.take());
+}
+
+/** Zero entries in every cache: the host must send bitmaps, never cache hits. */
+function bitmapCacheCapability() {
+  const writer = new Writer(40);
+  writer.zeros(24); // pad1..pad6
+  writer.u16le(0).u16le(0);
+  writer.u16le(0).u16le(0);
+  writer.u16le(0).u16le(0);
+  return capabilitySet(CAPSET.BITMAPCACHE, writer.take());
+}
+
+function controlCapability() {
+  const writer = new Writer(12);
+  writer.u16le(0);  // controlFlags
+  writer.u16le(0);  // remoteDetachFlag
+  writer.u16le(2);  // controlInterest: never
+  writer.u16le(2);  // detachInterest: never
+  return capabilitySet(CAPSET.CONTROL, writer.take());
+}
+
+function activationCapability() {
+  const writer = new Writer(12);
+  writer.u16le(0).u16le(0).u16le(0).u16le(0);
+  return capabilitySet(CAPSET.ACTIVATION, writer.take());
+}
+
+function pointerCapability() {
+  const writer = new Writer(10);
+  writer.u16le(1);   // colorPointerFlag
+  writer.u16le(20);  // colorPointerCacheSize
+  writer.u16le(20);  // pointerCacheSize
+  return capabilitySet(CAPSET.POINTER, writer.take());
+}
+
+function shareCapability() {
+  const writer = new Writer(8);
+  writer.u16le(0).u16le(0);
+  return capabilitySet(CAPSET.SHARE, writer.take());
+}
+
+function colorCacheCapability() {
+  const writer = new Writer(8);
+  writer.u16le(6).u16le(0);
+  return capabilitySet(CAPSET.COLORCACHE, writer.take());
+}
+
+function soundCapability() {
+  const writer = new Writer(8);
+  writer.u16le(0).u16le(0);
+  return capabilitySet(CAPSET.SOUND, writer.take());
+}
+
+function inputCapability(keyboardLayout: number) {
+  const writer = new Writer(88);
+  writer.u16le(INPUT_FLAG_SCANCODES | INPUT_FLAG_MOUSEX | INPUT_FLAG_UNICODE);
+  writer.u16le(0);                 // pad
+  writer.u32le(keyboardLayout);
+  writer.u32le(4);                 // keyboardType: IBM enhanced
+  writer.u32le(0);                 // keyboardSubType
+  writer.u32le(12);                // keyboardFunctionKey
+  writer.zeros(64);                // imeFileName
+  return capabilitySet(CAPSET.INPUT, writer.take());
+}
+
+function fontCapability() {
+  const writer = new Writer(8);
+  writer.u16le(1).u16le(0);
+  return capabilitySet(CAPSET.FONT, writer.take());
+}
+
+function brushCapability() {
+  const writer = new Writer(8);
+  writer.u32le(0); // BRUSH_DEFAULT
+  return capabilitySet(CAPSET.BRUSH, writer.take());
+}
+
+function glyphCacheCapability() {
+  const writer = new Writer(52);
+  for (let i = 0; i < 10; i++) writer.u16le(0).u16le(0); // GlyphCache entries
+  writer.u32le(0);  // FragCache
+  writer.u16le(0);  // GLYPH_SUPPORT_NONE
+  writer.u16le(0);  // pad
+  return capabilitySet(CAPSET.GLYPHCACHE, writer.take());
+}
+
+function offscreenCacheCapability() {
+  const writer = new Writer(12);
+  writer.u32le(0);  // offscreenSupportLevel: none
+  writer.u16le(0);  // offscreenCacheSize
+  writer.u16le(0);  // offscreenCacheEntries
+  return capabilitySet(CAPSET.OFFSCREENCACHE, writer.take());
+}
+
+function remoteProgramsCapability() {
+  const writer = new Writer(4);
+  writer.u32le(0x00000001); // TS_RAIL_LEVEL_SUPPORTED
+  return capabilitySet(CAPSET.RAIL, writer.take());
+}
+
+function windowListCapability(iconCaches = 0, iconCacheEntries = 0) {
+  const writer = new Writer(7);
+  writer.u32le(0x00000001); // TS_WINDOW_LEVEL_SUPPORTED
+  writer.u8(iconCaches);
+  writer.u16le(iconCacheEntries);
+  return capabilitySet(CAPSET.WINDOW, writer.take());
+}
+
+export function buildClientCapabilities({ width, height, keyboardLayout, remoteApp = false, remoteAppCaps = null }) {
+  const sets = [
+    generalCapability(),
+    bitmapCapability(width, height),
+    orderCapability(),
+    bitmapCacheCapability(),
+    colorCacheCapability(),
+    activationCapability(),
+    controlCapability(),
+    pointerCapability(),
+    shareCapability(),
+    inputCapability(keyboardLayout),
+    brushCapability(),
+    glyphCacheCapability(),
+    soundCapability(),
+    fontCapability(),
+    offscreenCacheCapability(),
+  ];
+
+  if (remoteApp) {
+    sets.push(remoteProgramsCapability());
+    sets.push(windowListCapability(
+      remoteAppCaps?.numIconCaches || 0,
+      remoteAppCaps?.numIconCacheEntries || 0
+    ));
+  }
+
+  return { bytes: concatBytes(...sets), count: sets.length };
+}
+
+/**
+ * Read the host's Demand Active capabilities. The desktop size it reports wins
+ * over anything the client asked for.
+ */
+export function parseServerCapabilities(bytes: Uint8Array) {
+  const reader = new Reader(bytes);
+  const numberCapabilities = reader.u16le();
+  reader.u16le(); // pad
+
+  const result = {
+    desktopWidth: 0,
+    desktopHeight: 0,
+    preferredBitsPerPixel: 16,
+    refreshRectSupport: false,
+    railSupportLevel: 0,
+    windowSupportLevel: 0,
+    numIconCaches: 0,
+    numIconCacheEntries: 0,
+    types: [],
+  };
+
+  for (let i = 0; i < numberCapabilities && reader.remaining >= 4; i++) {
+    const type = reader.u16le();
+    const length = reader.u16le();
+    if (length < 4 || length - 4 > reader.remaining) break;
+    const body = new Reader(reader.raw(length - 4));
+    result.types.push(type);
+
+    if (type === CAPSET.BITMAP && body.remaining >= 20) {
+      result.preferredBitsPerPixel = body.u16le();
+      body.skip(6); // receive1/4/8BitsPerPixel
+      result.desktopWidth = body.u16le();
+      result.desktopHeight = body.u16le();
+      continue;
+    }
+
+    if (type === CAPSET.GENERAL && body.remaining >= 20) {
+      body.skip(18);
+      result.refreshRectSupport = body.u8() !== 0;
+      continue;
+    }
+
+    if (type === CAPSET.RAIL && body.remaining >= 4) {
+      result.railSupportLevel = body.u32le();
+      continue;
+    }
+
+    if (type === CAPSET.WINDOW && body.remaining >= 7) {
+      result.windowSupportLevel = body.u32le();
+      result.numIconCaches = body.u8();
+      result.numIconCacheEntries = body.u16le();
+      continue;
+    }
+  }
+
+  return result;
+}