ai-remote 0.1.0

package/src/protocols/vnc/session.ts

@@ -0,0 +1,367 @@
+/**
+ * Everything VNC-specific, behind the driver interface the RDP side also
+ * implements. noVNC's RFB object does the protocol work; this module decides
+ * how it is addressed, constructed, controlled and explained.
+ *
+ * VNC splits the handshake differently from RDP: noVNC hands authentication to
+ * the Worker, because macOS Screen Sharing needs the Apple Diffie-Hellman
+ * (type 30) exchange that noVNC does not implement. That is why credentials
+ * travel in the URL here and never do for RDP.
+ */
+
+import RFB from '@novnc/novnc';
+import type {
+  DialogCopy,
+  DisconnectContext,
+  PointerButton,
+  ProtocolDriver,
+  RemoteSession,
+  ScreenGeometry,
+  SessionOptions,
+} from '../types';
+import type { ConnectionSettings } from '../../shared/connection';
+import { DEFAULT_PORTS } from '../../shared/protocol';
+import {
+  GATEWAY_KEEPALIVE_SIGNAL,
+  GATEWAY_READY_SIGNAL,
+  KEEPALIVE_INTERVAL_MS,
+} from '../../shared/signals';
+import { vncWheelMasks } from './input';
+
+const DIALOG: DialogCopy = {
+  usernameLabel: 'Username',
+  usernamePlaceholder: 'macOS username (optional)',
+  usernameHelp: 'Use your macOS account name. Leave it empty when the VNC server only asks for a password.',
+  passwordLabel: 'Password',
+  passwordPlaceholder: 'Screen sharing password',
+  passwordHelp: 'Use the macOS account password, or the password configured for VNC screen sharing.',
+  // A VNC session needs some secret; RDP can sign in on the host's own screen.
+  requiresPassword: true,
+};
+
+function buildUrl(origin: string, settings: ConnectionSettings): string {
+  const query = new URLSearchParams({ host: settings.host, port: String(settings.port) });
+  if (settings.username) query.set('vnc_user', settings.username);
+  if (settings.password) query.set('vnc_pass', settings.password);
+  return `${origin}/ws?${query}`;
+}
+
+/** Left = 1, middle = 2, right = 4, as RFB's button mask numbers them. */
+const BUTTON_MASK: Record<PointerButton, number> = { 0: 1, 1: 2, 2: 4 };
+
+function eventDetail(event: Event): Record<string, unknown> {
+  if (!('detail' in event)) return {};
+  const detail = event.detail;
+  if (!detail || typeof detail !== 'object') return {};
+  const copy: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(detail)) copy[key] = value;
+  return copy;
+}
+
+/**
+ * An RFB object given the control surface the RDP session already has, so the
+ * AI pane's screen tool never has to ask which protocol it is driving.
+ *
+ * This is a wrapper rather than a set of properties bolted onto the RFB
+ * instance: assigning methods onto someone else's object works until they add a
+ * member of the same name, and the type system cannot help when it happens.
+ */
+class VncSession extends EventTarget implements RemoteSession {
+  readonly protocol = 'vnc' as const;
+  readonly #rfb: RFB;
+  readonly #credentials: SessionOptions['credentials'];
+  #transport: WebSocket | null = null;
+  #keepalive: ReturnType<typeof setInterval> | null = null;
+  #readySent = false;
+  #close: { code: number; reason: string } | null = null;
+
+  constructor(container: HTMLElement, url: string, options: SessionOptions) {
+    super();
+
+    this.#credentials = options.credentials;
+    this.#rfb = new RFB(container, url, {
+      credentials: {
+        username: options.credentials.username,
+        password: options.credentials.password,
+      },
+      shared: true,
+      wsProtocols: ['binary'],
+    });
+
+    // On touch devices noVNC renders the remote pointer as a fixed canvas on
+    // document.body with the highest z-index on the page. Tag that fallback
+    // layer so the side panel can hide it; otherwise the Mac's large white
+    // pointer stays painted over terminal fields once the panel opens.
+    this.#rfb._cursor?._canvas?.classList.add('remote-cursor-overlay');
+
+    // Some VNC servers temporarily advertise a fully transparent cursor. Keep
+    // the normal remote cursor, but let noVNC's small dot fallback show while
+    // the advertised one has no visible pixels, so the pointer never vanishes.
+    this.#rfb.showDotCursor = true;
+
+    // Resizing the host to match the browser is right on a laptop and wrong on
+    // a phone, where it would turn a Mac desktop into a portrait strip.
+    this.#rfb.resizeSession = options.allowRemoteResize;
+    this.#rfb.clipViewport = true;
+    this.#rfb.scaleViewport = options.scaleViewport;
+    this.#rfb.viewOnly = options.viewOnly;
+    this.#rfb.qualityLevel = options.quality;
+    this.#rfb.compressionLevel = options.compression;
+
+    // RDP and SSH send these on the socket they own. noVNC owns the VNC
+    // socket, so this wrapper has to reach in and do the same: the gateway
+    // will not read the host until it sees GATEWAY_READY, and Cloudflare
+    // idles out a silent desktop after 100s without keepalives.
+    this.#bindTransport();
+
+    // Re-dispatch rather than have callers listen to two objects.
+    for (const name of ['connect', 'disconnect', 'credentialsrequired', 'desktopname', 'clipboard', 'bell'] as const) {
+      this.#rfb.addEventListener(name, (event) => {
+        if (name === 'credentialsrequired') {
+          this.#rfb.sendCredentials({
+            username: this.#credentials.username,
+            password: this.#credentials.password,
+          });
+        }
+
+        const detail = eventDetail(event);
+        if (name === 'disconnect' && this.#close) {
+          detail.code = this.#close.code;
+          detail.reason = this.#close.reason;
+        }
+        this.dispatchEvent(new CustomEvent(name, { detail }));
+      });
+    }
+  }
+
+  /**
+   * Attach to noVNC's WebSocket once it exists. Construction usually has it
+   * already; a retry covers the tick where `_sock._websocket` is still null.
+   */
+  #bindTransport(): void {
+    const attach = (): boolean => {
+      const ws = this.#rfb._sock?._websocket ?? null;
+      if (!ws || this.#transport === ws) return Boolean(ws);
+      this.#transport = ws;
+
+      const signalReady = () => {
+        if (this.#readySent || ws.readyState !== WebSocket.OPEN) return;
+        this.#readySent = true;
+        ws.send(GATEWAY_READY_SIGNAL);
+      };
+
+      ws.addEventListener('open', signalReady);
+      // Capture so the close code is stored before noVNC's `onclose` turns
+      // into a `disconnect` event that this wrapper re-dispatches.
+      ws.addEventListener('close', (event) => {
+        this.#close = { code: event.code, reason: event.reason ?? '' };
+        this.#stopKeepalive();
+      }, true);
+
+      this.#keepalive = setInterval(() => {
+        if (ws.readyState !== WebSocket.OPEN) return;
+        try {
+          ws.send(GATEWAY_KEEPALIVE_SIGNAL);
+
+          // The text frame above stops at the gateway, so it cannot keep the
+          // VPC/Tunnel TCP leg alive. A one-pixel incremental request is a
+          // normal RFB message, changes no state, and keeps an idle desktop's
+          // origin connection active just as RDP and SSH do with their own
+          // protocol-level keepalives.
+          const sock = this.#rfb._sock;
+          if (sock && this.#rfb._rfbConnectionState === 'connected') {
+            RFB.messages.fbUpdateRequest(sock, true, 0, 0, 1, 1);
+          }
+        } catch {
+          // A keepalive is not worth breaking a working session over.
+        }
+      }, KEEPALIVE_INTERVAL_MS);
+
+      signalReady();
+      return true;
+    };
+
+    if (attach()) return;
+
+    let tries = 0;
+    const timer = setInterval(() => {
+      if (attach() || ++tries > 20) clearInterval(timer);
+    }, 25);
+  }
+
+  #stopKeepalive(): void {
+    if (this.#keepalive) clearInterval(this.#keepalive);
+    this.#keepalive = null;
+  }
+
+  get connected(): boolean {
+    return this.#rfb._rfbConnectionState === 'connected';
+  }
+
+  get socket(): WebSocket | null {
+    return this.#rfb._sock?._websocket ?? null;
+  }
+
+  get canvas(): HTMLCanvasElement | null {
+    return this.#rfb._canvas;
+  }
+
+  get scaleViewport(): boolean {
+    return this.#rfb.scaleViewport;
+  }
+
+  set scaleViewport(enabled: boolean) {
+    this.#rfb.scaleViewport = enabled;
+  }
+
+  get viewOnly(): boolean {
+    return this.#rfb.viewOnly;
+  }
+
+  set viewOnly(enabled: boolean) {
+    this.#rfb.viewOnly = enabled;
+  }
+
+  get qualityLevel(): number {
+    return this.#rfb.qualityLevel;
+  }
+
+  set qualityLevel(level: number) {
+    this.#rfb.qualityLevel = level;
+  }
+
+  get compressionLevel(): number {
+    return this.#rfb.compressionLevel;
+  }
+
+  set compressionLevel(level: number) {
+    this.#rfb.compressionLevel = level;
+  }
+
+  get screenGeometry(): ScreenGeometry {
+    const width = this.#rfb._fbWidth || 0;
+    const height = this.#rfb._fbHeight || 0;
+    return { width, height, viewport: { x: 0, y: 0, width, height } };
+  }
+
+  /** Internal state worth logging once the first server frame has been parsed. */
+  describeState(): Record<string, unknown> {
+    const socket = this.#rfb._sock;
+    return {
+      connectionState: this.#rfb._rfbConnectionState,
+      initializationState: this.#rfb._rfbInitState,
+      queuedReceiveBytes: Math.max(0, (socket?._rQlen ?? 0) - (socket?._rQi ?? 0)),
+    };
+  }
+
+  disconnect(): void {
+    this.#stopKeepalive();
+    this.#rfb.disconnect();
+  }
+
+  sendKey(keysym: number, code: string | null, down?: boolean): void {
+    this.#rfb.sendKey(keysym, code, down);
+  }
+
+  sendClipboard(text: string): void {
+    this.#rfb.clipboardPasteFrom(text);
+  }
+
+  releaseKeyboard(): void {
+    // noVNC ungrabs the keyboard when its canvas loses focus.
+    this.#rfb.blur();
+  }
+
+  /**
+   * noVNC keeps pointer input private -- its own handlers translate browser
+   * events into framebuffer coordinates first -- so this reaches for the same
+   * wire helper `_sendMouse` ends at, with coordinates already in pixels.
+   */
+  #pointer(x: number, y: number, mask: number): boolean {
+    const socket = this.#rfb._sock;
+    if (!socket || this.#rfb._rfbConnectionState !== 'connected' || this.#rfb.viewOnly) return false;
+
+    const width = this.#rfb._fbWidth || 1;
+    const height = this.#rfb._fbHeight || 1;
+    RFB.messages.pointerEvent(
+      socket,
+      Math.max(0, Math.min(width - 1, Math.round(x))),
+      Math.max(0, Math.min(height - 1, Math.round(y))),
+      mask
+    );
+    return true;
+  }
+
+  movePointer(x: number, y: number): boolean {
+    return this.#pointer(x, y, 0);
+  }
+
+  clickPointer(x: number, y: number, button: PointerButton = 0): boolean {
+    if (!this.#pointer(x, y, 0)) return false;
+    this.#pointer(x, y, BUTTON_MASK[button]);
+    this.#pointer(x, y, 0);
+    return true;
+  }
+
+  pointerButton(x: number, y: number, button: PointerButton = 0, pressed = true): boolean {
+    return this.#pointer(x, y, pressed ? BUTTON_MASK[button] : 0);
+  }
+
+  scrollPointer(x: number, y: number, delta: { x: number; y: number }): boolean {
+    // RFB represents wheels as buttons: 4/5 are up/down and 6/7 are left/right.
+    // The tool boundary already limits each axis, but keep the wire path bounded
+    // too because other callers may be added later.
+    for (const mask of vncWheelMasks(delta)) {
+      if (!this.#pointer(x, y, mask)) return false;
+      if (!this.#pointer(x, y, 0)) return false;
+    }
+    return true;
+  }
+
+  /**
+   * VNC has no Unicode input message, so text is typed as keysyms. For every
+   * character in the Basic Multilingual Plane the keysym is the code point.
+   */
+  typeText(text: string): boolean {
+    if (this.#rfb._rfbConnectionState !== 'connected' || this.#rfb.viewOnly || !text) return false;
+
+    for (const character of text) {
+      const point = character.codePointAt(0) ?? 0;
+      const keysym = character === '\n' ? 0xff0d : character === '\t' ? 0xff09 : point;
+      this.#rfb.sendKey(keysym, null, true);
+      this.#rfb.sendKey(keysym, null, false);
+    }
+    return true;
+  }
+}
+
+/**
+ * Turn a close code and the gateway's reason into something a person can act
+ * on. Returns null when nothing VNC-specific applies, leaving the shared text.
+ */
+function describeDisconnect({ code, reason, suffix }: DisconnectContext): string | null {
+  if (code === 4001 || /auth|password|credential/i.test(reason)) {
+    return `VNC authentication failed${suffix}. Verify the macOS account username and its password.`;
+  }
+  if (code === 4002 || /apple dh/i.test(reason)) {
+    return `macOS VNC authentication handshake failed${suffix}.`;
+  }
+  if (code === 1011 || /cannot connect|unreachable|tcp error|tcp write/i.test(reason)) {
+    return `The Worker could not keep a TCP connection to the VNC host${suffix}. `
+      + 'Check that Screen Sharing is running and listening on this address.';
+  }
+  return null;
+}
+
+export const vncDriver: ProtocolDriver = {
+  protocol: 'vnc',
+  label: 'VNC Client',
+  defaultPort: DEFAULT_PORTS.vnc,
+  dialog: DIALOG,
+  buildUrl,
+  createSession: (container, url, options) => new VncSession(container, url, options),
+  describeState: (session) => (
+    session instanceof VncSession ? session.describeState() : {}
+  ),
+  describeDisconnect,
+};

package/src/shared/connection.ts

@@ -0,0 +1,206 @@
+/**
+ * One connection, described once.
+ *
+ * Every way of starting a session -- a saved card on the welcome screen, an
+ * address typed by hand, a RemoteApp launcher, a reconnect after a drop --
+ * produces exactly this shape and hands it to exactly one dialog. That is the
+ * whole point of the type: before it existed, a saved card could only ask for a
+ * username and a password, so its port, security layer, domain and picture
+ * quality were unreachable once the card had been made.
+ */
+
+import {
+  DEFAULT_PORTS,
+  toPort,
+  toRdpSecurity,
+  toRemoteProtocol,
+  type RdpSecurity,
+  type RemoteProtocol,
+} from './protocol';
+
+/** A published Windows application launched instead of the full desktop. */
+export interface RemoteAppLaunch {
+  /** Alias (`||notepad`) or an executable path. */
+  program: string;
+  workingDir?: string;
+  arguments?: string;
+}
+
+/** The companion terminal offered beside a desktop. */
+export interface SshCompanion {
+  enabled: boolean;
+  port: number;
+  username: string;
+}
+
+/** Picture and input options. VNC negotiates them; RDP and SSH ignore what does not apply. */
+export interface DisplaySettings {
+  /** RFB quality level, 1 (smallest) to 9 (sharpest). */
+  quality: number;
+  /** RFB compression level, 0 (fastest) to 9 (smallest). */
+  compression: number;
+  /** Fit the remote desktop to the pane rather than scrolling it. */
+  scaling: boolean;
+  /** Watch without sending keyboard or pointer input. */
+  viewOnly: boolean;
+}
+
+/**
+ * Everything a session needs. `password` is the only field never persisted
+ * anywhere -- not in the device library on the gateway, not in localStorage.
+ */
+export interface ConnectionSettings {
+  /** Stable identity: protocol, address, port and program. See {@link connectionId}. */
+  id: string;
+  label: string;
+
+  protocol: RemoteProtocol;
+  host: string;
+  port: number;
+
+  username: string;
+  password: string;
+  /** Windows domain or computer name. RDP only. */
+  domain: string;
+
+  security: RdpSecurity;
+  remoteApp: RemoteAppLaunch | null;
+
+  display: DisplaySettings;
+  ssh: SshCompanion;
+  /** Open the terminal panel as soon as the desktop appears. */
+  openSshOnConnect: boolean;
+}
+
+export const DEFAULT_DISPLAY_SETTINGS: DisplaySettings = {
+  quality: 6,
+  compression: 2,
+  scaling: true,
+  viewOnly: false,
+};
+
+/**
+ * A connection's identity is what it points at, not when it was made. Editing
+ * the address therefore makes a different connection rather than silently
+ * repointing an existing card, which is the behaviour people expect from a
+ * list of machines.
+ */
+export function connectionId(
+  input: Pick<ConnectionSettings, 'protocol' | 'host' | 'port'> & { remoteApp?: RemoteAppLaunch | null }
+): string {
+  const program = input.remoteApp?.program?.trim() ?? '';
+  const base = `${input.protocol || 'vnc'}:${input.host.trim()}:${input.port || ''}`;
+  // This format is load-bearing, not arbitrary: device libraries already on
+  // disk are keyed by it. Change it and every saved machine turns into a
+  // second, empty card the first time someone connects to it again.
+  return (program ? `${base}:${program}` : base).toLowerCase().slice(0, 64);
+}
+
+/** A blank connection, ready for the dialog to fill in. */
+export function emptyConnection(protocol: RemoteProtocol = 'vnc'): ConnectionSettings {
+  const port = DEFAULT_PORTS[protocol];
+  return {
+    id: '',
+    label: '',
+    protocol,
+    host: '',
+    port,
+    username: '',
+    password: '',
+    domain: '',
+    security: 'auto',
+    remoteApp: null,
+    display: { ...DEFAULT_DISPLAY_SETTINGS },
+    ssh: { enabled: false, port: DEFAULT_PORTS.ssh, username: '' },
+    openSshOnConnect: false,
+  };
+}
+
+function clampLevel(value: unknown, fallback: number, min: number, max: number): number {
+  const level = typeof value === 'number' ? value : Number.parseInt(String(value ?? ''), 10);
+  if (!Number.isInteger(level)) return fallback;
+  return Math.min(max, Math.max(min, level));
+}
+
+export function normalizeDisplaySettings(value: unknown): DisplaySettings {
+  const input = (value ?? {}) as Partial<DisplaySettings>;
+  return {
+    quality: clampLevel(input.quality, DEFAULT_DISPLAY_SETTINGS.quality, 1, 9),
+    compression: clampLevel(input.compression, DEFAULT_DISPLAY_SETTINGS.compression, 0, 9),
+    scaling: typeof input.scaling === 'boolean' ? input.scaling : DEFAULT_DISPLAY_SETTINGS.scaling,
+    viewOnly: Boolean(input.viewOnly),
+  };
+}
+
+function normalizeRemoteApp(value: unknown): RemoteAppLaunch | null {
+  if (typeof value === 'string') {
+    const program = value.trim();
+    return program ? { program } : null;
+  }
+  if (!value || typeof value !== 'object') return null;
+
+  const input = value as Record<string, unknown>;
+  const program = String(input.program ?? '').trim();
+  if (!program) return null;
+
+  const workingDir = String(input.workingDir ?? '').trim();
+  const args = String(input.arguments ?? '').trim();
+  return {
+    program,
+    ...(workingDir ? { workingDir } : {}),
+    ...(args ? { arguments: args } : {}),
+  };
+}
+
+/**
+ * Build a complete, valid connection out of whatever a caller happens to have.
+ * Partial input from a saved card, a host list entry, a URL or localStorage all
+ * arrive here, so the dialog never has to reason about missing fields.
+ */
+export function normalizeConnection(input: Partial<ConnectionSettings> & Record<string, unknown>): ConnectionSettings {
+  const protocol = toRemoteProtocol(input.protocol);
+  const host = String(input.host ?? '').trim();
+  const port = toPort(input.port, DEFAULT_PORTS[protocol]);
+  const remoteApp = normalizeRemoteApp(input.remoteApp ?? input.program);
+
+  const sshInput = (input.ssh ?? {}) as Partial<SshCompanion>;
+  const ssh: SshCompanion = {
+    enabled: Boolean(sshInput.enabled),
+    port: toPort(sshInput.port, DEFAULT_PORTS.ssh),
+    username: String(sshInput.username ?? '').trim(),
+  };
+
+  const settings: ConnectionSettings = {
+    id: '',
+    label: String(input.label ?? '').trim() || host,
+    protocol,
+    host,
+    port,
+    username: String(input.username ?? '').trim(),
+    password: String(input.password ?? ''),
+    domain: String(input.domain ?? '').trim(),
+    security: toRdpSecurity(input.security),
+    remoteApp,
+    display: normalizeDisplaySettings(input.display),
+    ssh,
+    openSshOnConnect: Boolean(input.openSshOnConnect),
+  };
+
+  settings.id = String(input.id ?? '').trim() || connectionId(settings);
+  return settings;
+}
+
+/** What a connection is worth remembering by -- never the password. */
+export type PersistedConnection = Omit<ConnectionSettings, 'password'>;
+
+export function withoutPassword(settings: ConnectionSettings): PersistedConnection {
+  const { password: _password, ...rest } = settings;
+  return rest;
+}
+
+/** A one-line description for the dialog's summary row and the status bar. */
+export function describeConnection(settings: ConnectionSettings): string {
+  const target = `${settings.host || 'no address'}:${settings.port}`;
+  const app = settings.remoteApp ? ` · ${settings.remoteApp.program}` : '';
+  return `${settings.protocol.toUpperCase()} · ${target}${app}`;
+}

package/src/shared/device.ts

@@ -0,0 +1,28 @@
+/**
+ * A machine as the gateway remembers it, shared by the Durable Object that
+ * stores the record and the welcome screen that draws it.
+ *
+ * Passwords and account names are deliberately absent: the gateway has no need
+ * of them and every reason not to hold them. They live in the browser, next to
+ * the rest of the connection's settings.
+ */
+
+import type { RdpSecurity, RemoteProtocol } from './protocol';
+
+export interface SavedDevice {
+  id: string;
+  label: string;
+  host: string;
+  port: number;
+  protocol: RemoteProtocol;
+  domain?: string;
+  security?: RdpSecurity;
+  /** RemoteApp alias (`||notepad`) when this card launches an app, not a desktop. */
+  program?: string;
+  favorite?: boolean;
+  /** Milliseconds since the epoch; drives the "recent" ordering. */
+  lastUsed?: number;
+  createdAt?: number;
+  /** Set when a thumbnail exists, so the client can cache-bust its <img>. */
+  thumbnailAt?: number;
+}