ai-remote 0.1.0

package/src/protocols/ssh/wire.ts

@@ -0,0 +1,220 @@
+// SSH wire types (RFC 4251 section 5).
+//
+// Everything in SSH is big endian, so unlike the RDP reader and writer the byte
+// order is not part of each call. The four types that matter here are the
+// 32-bit length-prefixed string, the multiple-precision integer, the name-list
+// and the byte.
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+export function encodeUtf8(text: string): Uint8Array {
+  return textEncoder.encode(text);
+}
+
+export function decodeUtf8(bytes: Uint8Array): string {
+  return textDecoder.decode(bytes);
+}
+
+export function concatBytes(...parts: readonly Uint8Array[]): Uint8Array {
+  const total = parts.reduce((sum, part) => sum + part.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const part of parts) {
+    out.set(part, offset);
+    offset += part.length;
+  }
+  return out;
+}
+
+/** Constant-time-ish equality. Used for authentication tags and fingerprints. */
+export function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let difference = 0;
+  for (let index = 0; index < a.length; index++) difference |= (a[index] ?? 0) ^ (b[index] ?? 0);
+  return difference === 0;
+}
+
+export function toBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+export function fromBase64(text: string): Uint8Array {
+  const binary = atob(text);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+  return bytes;
+}
+
+/** Base64url without padding, which is what a JSON Web Key wants. */
+export function toBase64Url(bytes: Uint8Array): string {
+  return toBase64(bytes).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
+}
+
+export class SshWriter {
+  private bytes: Uint8Array<ArrayBuffer>;
+  private view: DataView;
+  private offset = 0;
+
+  constructor(capacity = 256) {
+    this.bytes = new Uint8Array(new ArrayBuffer(capacity));
+    this.view = new DataView(this.bytes.buffer);
+  }
+
+  #ensure(extra: number): void {
+    if (this.offset + extra <= this.bytes.length) return;
+    let capacity = Math.max(this.bytes.length * 2, 64);
+    while (capacity < this.offset + extra) capacity *= 2;
+    const grown = new Uint8Array(new ArrayBuffer(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;
+  }
+
+  boolean(value: boolean): this {
+    return this.u8(value ? 1 : 0);
+  }
+
+  u32(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;
+  }
+
+  /** A length-prefixed string. Text is encoded as UTF-8. */
+  string(value: string | Uint8Array): this {
+    const bytes = typeof value === 'string' ? encodeUtf8(value) : value;
+    return this.u32(bytes.length).raw(bytes);
+  }
+
+  nameList(names: readonly string[]): this {
+    return this.string(names.join(','));
+  }
+
+  /**
+   * An mpint: two's complement, big endian, with no leading zero bytes except
+   * the one that keeps a positive number from looking negative.
+   */
+  mpint(bytes: Uint8Array): this {
+    let start = 0;
+    while (start < bytes.length && bytes[start] === 0) start++;
+    const magnitude = bytes.subarray(start);
+    if (magnitude.length === 0) return this.u32(0);
+    if ((magnitude[0] ?? 0) & 0x80) {
+      this.u32(magnitude.length + 1).u8(0);
+      return this.raw(magnitude);
+    }
+    return this.u32(magnitude.length).raw(magnitude);
+  }
+
+  get length(): number {
+    return this.offset;
+  }
+
+  take(): Uint8Array {
+    return this.bytes.slice(0, this.offset);
+  }
+}
+
+export class SshReader {
+  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 (count < 0 || this.remaining < count) {
+      throw new Error(`SSH: truncated packet (needed ${count} bytes, ${this.remaining} left)`);
+    }
+  }
+
+  u8(): number {
+    this.#need(1);
+    return this.view.getUint8(this.offset++);
+  }
+
+  boolean(): boolean {
+    return this.u8() !== 0;
+  }
+
+  u32(): 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;
+  }
+
+  /** The bytes of a length-prefixed string. */
+  stringBytes(): Uint8Array {
+    return this.raw(this.u32());
+  }
+
+  string(): string {
+    return decodeUtf8(this.stringBytes());
+  }
+
+  nameList(): string[] {
+    const value = this.string();
+    return value ? value.split(',') : [];
+  }
+
+  /** An mpint's magnitude, with the sign byte removed. */
+  mpint(): Uint8Array {
+    const bytes = this.stringBytes();
+    let start = 0;
+    while (start < bytes.length && bytes[start] === 0) start++;
+    return bytes.subarray(start);
+  }
+
+  skip(count: number): this {
+    this.#need(count);
+    this.offset += count;
+    return this;
+  }
+
+  rest(): Uint8Array {
+    return this.bytes.subarray(this.offset);
+  }
+}
+
+/** Pad a magnitude out to a fixed width, which raw curve points need. */
+export function padStart(bytes: Uint8Array, width: number): Uint8Array {
+  if (bytes.length === width) return bytes;
+  if (bytes.length > width) return bytes.subarray(bytes.length - width);
+  const out = new Uint8Array(width);
+  out.set(bytes, width - bytes.length);
+  return out;
+}

package/src/protocols/types.ts

@@ -0,0 +1,146 @@
+/**
+ * The interface every remote-desktop protocol presents to the UI.
+ *
+ * The workspace -- toolbar, stats rail, on-screen keyboard, reconnects -- does
+ * not care whether a session is VNC or RDP. Everything that does differ is
+ * reached through this interface instead of branching at each call site.
+ */
+
+import type { ConnectionSettings, RemoteAppLaunch } from '../shared/connection';
+import type { RdpSecurity, RemoteProtocol } from '../shared/protocol';
+
+/** Where the pointer may go, in framebuffer pixels. */
+export interface ScreenGeometry {
+  width: number;
+  height: number;
+  viewport: { x: number; y: number; width: number; height: number };
+}
+
+/** Mouse buttons, as the UI names them. */
+export type PointerButton = 0 | 1 | 2;
+
+/** Wheel movement in discrete remote-protocol notches. Positive is right/down. */
+export interface ScrollDelta {
+  x: number;
+  y: number;
+}
+
+/**
+ * A live session. Both drivers expose this, so the AI pane's screen tool and
+ * the toolbar never have to ask which protocol they are driving.
+ */
+export interface RemoteSession extends EventTarget {
+  readonly protocol: RemoteProtocol;
+  disconnect(): void;
+
+  /** True once the desktop has been reached. */
+  readonly connected: boolean;
+
+  /** Fit the remote desktop to the pane rather than scrolling it. */
+  scaleViewport: boolean;
+  /** Watch without sending keyboard or pointer input. */
+  viewOnly: boolean;
+  /** RFB quality level. RDP ignores it. */
+  qualityLevel?: number;
+  /** RFB compression level. RDP ignores it. */
+  compressionLevel?: number;
+
+  /** The transport the metrics rail instruments. Can appear a tick after construction. */
+  readonly socket?: WebSocket | null;
+
+  readonly screenGeometry: ScreenGeometry;
+
+  movePointer(x: number, y: number): boolean;
+  clickPointer(x: number, y: number, button?: PointerButton): boolean;
+  pointerButton(x: number, y: number, button?: PointerButton, pressed?: boolean): boolean;
+  scrollPointer(x: number, y: number, delta: ScrollDelta): boolean;
+  typeText(text: string): boolean;
+
+  /** Prefer the protocol clipboard for longer text when it can paste reliably. */
+  pasteText?(text: string): boolean | Promise<boolean>;
+
+  /** Press or release one key by keysym. */
+  sendKey(keysym: number, code: string | null, down?: boolean): void;
+
+  /** Send text to the host's clipboard, when the protocol carries one. */
+  sendClipboard?(text: string): void;
+
+  /**
+   * Stop taking keystrokes: the workspace has given the keyboard to something
+   * local, such as the terminal or the assistant's message box.
+   *
+   * Both protocols listen on the element they paint into, so a key only leaves
+   * for the host while that element holds focus. Handing focus back is the
+   * whole mechanism -- plus, for RDP, letting go of anything still held down,
+   * which would otherwise stay down on the far side.
+   */
+  releaseKeyboard?(): void;
+
+  /** Ask the host for a different desktop size, when the protocol allows it. */
+  requestDesktopSize?(width: number, height: number): void;
+
+  /** The canvas the session paints into, for screenshots and thumbnails. */
+  readonly canvas?: HTMLCanvasElement | null;
+}
+
+/** What the workspace hands a driver to open a session. */
+export interface SessionOptions {
+  credentials: { username: string; password: string };
+  domain: string;
+  security: RdpSecurity;
+  remoteApp: RemoteAppLaunch | null;
+
+  /** Desktop size to ask the host for. */
+  width: number;
+  height: number;
+  /** False on a phone, where resizing the host would make a portrait strip of it. */
+  allowRemoteResize: boolean;
+
+  scaleViewport: boolean;
+  viewOnly: boolean;
+  quality: number;
+  compression: number;
+
+  /** Shown in this driver's own log lines. */
+  hostLabel: string;
+}
+
+/** Wording for the one connect dialog, which is shared markup across protocols. */
+export interface DialogCopy {
+  usernameLabel: string;
+  usernamePlaceholder: string;
+  usernameHelp: string;
+  passwordLabel: string;
+  passwordPlaceholder: string;
+  passwordHelp: string;
+  /** A VNC session needs some secret; RDP can sign in on the host's own screen. */
+  requiresPassword: boolean;
+}
+
+/** Everything the UI knows about a close, before anyone tries to explain it. */
+export interface DisconnectContext {
+  code?: number;
+  reason: string;
+  /** Pre-rendered ` (WebSocket 1006: ...)` tail, so wording stays consistent. */
+  suffix: string;
+}
+
+/** One protocol implementation. */
+export interface ProtocolDriver {
+  readonly protocol: RemoteProtocol;
+  /** Used as the prefix of this driver's console lines. */
+  readonly label: string;
+  readonly defaultPort: number;
+  readonly dialog: DialogCopy;
+
+  /** The gateway endpoint for this connection, including any query it needs. */
+  buildUrl(origin: string, settings: ConnectionSettings): string;
+
+  createSession(container: HTMLElement, url: string, options: SessionOptions): RemoteSession;
+
+  /** Extra detail worth logging once the first server frame has been parsed. */
+  describeState(session: RemoteSession): Record<string, unknown>;
+
+  /** Protocol-specific wording for a close, or null to fall back to the shared text. */
+  describeDisconnect(context: DisconnectContext): string | null;
+}

package/src/protocols/vnc/input.ts

@@ -0,0 +1,13 @@
+/** RFB wheel buttons for a bounded two-axis scroll, in wire order. */
+export function vncWheelMasks(delta: { x: number; y: number }): number[] {
+  const masks: number[] = [];
+  const wheels = [
+    { amount: delta.y, negativeMask: 1 << 3, positiveMask: 1 << 4 },
+    { amount: delta.x, negativeMask: 1 << 5, positiveMask: 1 << 6 },
+  ];
+  for (const { amount, negativeMask, positiveMask } of wheels) {
+    const mask = amount < 0 ? negativeMask : positiveMask;
+    for (let step = 0; step < Math.min(20, Math.abs(amount)); step++) masks.push(mask);
+  }
+  return masks;
+}

package/src/protocols/vnc/novnc.d.ts

@@ -0,0 +1,75 @@
+/**
+ * noVNC ships no type declarations, so this is the surface this project uses.
+ *
+ * It deliberately includes the underscore-prefixed internals the VNC driver
+ * reaches for. Those are private by convention, and naming them here is the
+ * honest record of that: the pointer helpers need framebuffer-space coordinates,
+ * which noVNC's own event handlers compute and then keep to themselves.
+ */
+
+declare module '@novnc/novnc' {
+  export interface RfbCredentials {
+    username?: string;
+    password?: string;
+    target?: string;
+  }
+
+  export interface RfbOptions {
+    credentials?: RfbCredentials;
+    shared?: boolean;
+    repeaterID?: string;
+    wsProtocols?: string[];
+  }
+
+  /** noVNC's own socket wrapper. `_websocket` is the transport underneath. */
+  export interface RfbSocket {
+    _websocket: WebSocket | null;
+    _rQlen: number;
+    _rQi: number;
+  }
+
+  export default class RFB extends EventTarget {
+    constructor(target: HTMLElement, url: string, options?: RfbOptions);
+
+    static messages: {
+      fbUpdateRequest(
+        sock: RfbSocket,
+        incremental: boolean,
+        x: number,
+        y: number,
+        width: number,
+        height: number
+      ): void;
+      pointerEvent(sock: RfbSocket, x: number, y: number, mask: number): void;
+    };
+
+    disconnect(): void;
+    sendCredentials(credentials: RfbCredentials): void;
+    sendKey(keysym: number, code: string | null, down?: boolean): void;
+    sendCtrlAltDel(): void;
+    clipboardPasteFrom(text: string): void;
+    focus(): void;
+    blur(): void;
+    machineShutdown(): void;
+
+    viewOnly: boolean;
+    scaleViewport: boolean;
+    resizeSession: boolean;
+    clipViewport: boolean;
+    showDotCursor: boolean;
+    qualityLevel: number;
+    compressionLevel: number;
+    background: string;
+
+    readonly capabilities: { power: boolean };
+
+    /** 'connecting' | 'connected' | 'disconnecting' | 'disconnected'. */
+    _rfbConnectionState: string;
+    _rfbInitState: string;
+    _fbWidth: number;
+    _fbHeight: number;
+    _sock: RfbSocket | null;
+    _canvas: HTMLCanvasElement | null;
+    _cursor: { _canvas: HTMLCanvasElement | null } | null;
+  }
+}