ai-remote 0.4.8 → 0.4.10

package/README.md

@@ -92,6 +92,12 @@ npx ai-remote shot -o screen.png
 npx ai-remote click 640,400
 ```
 
+When a Mac offers both account authentication and the legacy VNC-password
+challenge, `-u NAME` selects the account exchange and attaches to that user's
+desktop. Omit `-u` to use the legacy VNC password instead. Add `--save` after a
+successful first connection to keep the password in the macOS login Keychain;
+later connections can use `--no-prompt`.
+
 The client is this package's own: no noVNC, no browser and no gateway. It signs
 in either way a host may ask -- the classic VNC password, or the account and
 password macOS Screen Sharing wants -- and decodes Raw and CopyRect, which

package/dist/cli.mjs

@@ -7649,6 +7649,8 @@ var ENCODING = {
   LAST_RECT: -224
 };
 var SECURITY = { NONE: 1, VNC: 2, APPLE_DH: 30 };
+var ACTIVE_UPDATE_INTERVAL_MS = 1e3 / 30;
+var IDLE_UPDATE_INTERVAL_MS = 100;
 var SECURITY_NAME = {
   0: "invalid",
   1: "none",
@@ -7800,13 +7802,16 @@ var RfbClient = class extends EventTarget {
   /**
    * Which way to sign in.
    *
-   * A password challenge is preferred where the host offers one: it is the same
-   * everywhere. Apple's exchange comes next, because on macOS it is usually the
-   * only thing offered -- Screen Sharing wants an account, not a VNC password,
-   * unless somebody has turned the legacy one on.
+   * A named account means the caller wants Apple's account exchange when the
+   * host offers it. macOS can advertise that beside the legacy VNC-password
+   * challenge; choosing the challenge first ignores the account and attaches to
+   * loginwindow instead of the named user's desktop. Without an account, keep
+   * preferring the portable VNC-password challenge.
    */
   #chooseSecurity(offered) {
+    const username = this.options.username ?? "";
     const password2 = this.options.password ?? "";
+    if (username && password2 && offered.includes(SECURITY.APPLE_DH)) return SECURITY.APPLE_DH;
     if (password2 && offered.includes(SECURITY.VNC)) return SECURITY.VNC;
     if (password2 && offered.includes(SECURITY.APPLE_DH)) return SECURITY.APPLE_DH;
     if (offered.includes(SECURITY.NONE)) return SECURITY.NONE;
@@ -7886,7 +7891,12 @@ var RfbClient = class extends EventTarget {
     while (!this.#closed) {
       const [type] = await this.#read(1);
       if (type === SERVER.FRAMEBUFFER_UPDATE) {
-        await this.#framebufferUpdate();
+        const started = Date.now();
+        const changed = await this.#framebufferUpdate();
+        const interval = changed ? ACTIVE_UPDATE_INTERVAL_MS : IDLE_UPDATE_INTERVAL_MS;
+        const remaining = interval - (Date.now() - started);
+        if (remaining > 0) await new Promise((resolve) => setTimeout(resolve, remaining));
+        if (this.#closed) break;
         this.#requestUpdate(!this.#wantFull);
         continue;
       }
@@ -7951,6 +7961,7 @@ var RfbClient = class extends EventTarget {
     if (rects.length) {
       this.dispatchEvent(new CustomEvent("paint", { detail: { rects } }));
     }
+    return resized || rects.length > 0;
   }
   // --- the byte stream -------------------------------------------------------------
   #feed(bytes) {
@@ -9799,7 +9810,7 @@ async function runWindow(argv) {
       }
     }, 400);
   }
-  await application.whenReady();
+  await application.whenReady({ interval: 100 });
 }
 
 // src/cli/generated/viewer-bundle.ts

package/dist/index.d.ts

@@ -1,13 +1,255 @@
 /**
- * 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';
+ * The vocabulary both halves of the gateway share.
+ *
+ * The Worker and the browser have to agree on what a "protocol" is, what ports
+ * they default to and how an RDP security layer is named, so those live here
+ * rather than being re-declared on each side and drifting apart.
+ */
+/** A remote-desktop protocol the session workspace can display. */
+export declare const REMOTE_PROTOCOLS: readonly ['vnc', 'rdp'];
+export type RemoteProtocol = (typeof REMOTE_PROTOCOLS)[number];
+/** Every protocol the gateway relays, including the terminal side panel. */
+export declare const TRANSPORT_PROTOCOLS: readonly ['vnc', 'rdp', 'ssh'];
+export type TransportProtocol = (typeof TRANSPORT_PROTOCOLS)[number];
+/**
+ * The RDP security layer. `auto` negotiates with the host, which is right for
+ * anything that answers honestly; the rest are for hosts that do not.
+ */
+export declare const RDP_SECURITY_MODES: readonly ['auto', 'nla', 'tls', 'rdp'];
+export type RdpSecurity = (typeof RDP_SECURITY_MODES)[number];
+export declare const DEFAULT_PORTS: Record<TransportProtocol, number>;
+export declare const DEFAULT_SSH_PORT: number;
+/** Max time allowed before command start output is detected. */
+export declare const COMMAND_START_MS = 15000;
+/** Max idle silence allowed during command execution. */
+export declare const COMMAND_IDLE_MS: number;
+export declare function isRemoteProtocol(value: unknown): value is RemoteProtocol;
+export declare function isRdpSecurity(value: unknown): value is RdpSecurity;
+/** Coerce anything to a protocol, falling back to what the caller opens on. */
+export declare function toRemoteProtocol(value: unknown, fallback?: RemoteProtocol): RemoteProtocol;
+export declare function toRdpSecurity(value: unknown, fallback?: RdpSecurity): RdpSecurity;
+/** A port number, or the protocol's default when the value is not one. */
+export declare function toPort(value: unknown, fallback: number): number;
+/** 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 declare const DEFAULT_DISPLAY_SETTINGS: DisplaySettings;
+/**
+ * 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 declare function connectionId(input: Pick<ConnectionSettings, 'protocol' | 'host' | 'port'> & {
+    remoteApp?: RemoteAppLaunch | null;
+}): string;
+/** A blank connection, ready for the dialog to fill in. */
+export declare function emptyConnection(protocol?: RemoteProtocol): ConnectionSettings;
+export declare function normalizeDisplaySettings(value: unknown): DisplaySettings;
+/**
+ * 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 declare function normalizeConnection(input: Partial<ConnectionSettings> & Record<string, unknown>): ConnectionSettings;
+/** What a connection is worth remembering by -- never the password. */
+export type PersistedConnection = Omit<ConnectionSettings, 'password'>;
+export declare function withoutPassword(settings: ConnectionSettings): PersistedConnection;
+/** A one-line description for the dialog's summary row and the status bar. */
+export declare function describeConnection(settings: ConnectionSettings): string;
+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;
+}
+/** Optional SSH access to the same machine, which publishes a terminal for it. */
+export interface HostSshAccess {
+    port: number;
+    username?: string;
+}
+/** One machine as the gateway's configuration describes it. */
+export interface RemoteHostTarget {
+    id: string;
+    name: string;
+    host: string;
+    port: number;
+    protocol: RemoteProtocol;
+    /** Windows domain or computer name pre-filled in the connect dialog. */
+    domain?: string;
+    security?: RdpSecurity;
+    remoteApp?: RemoteAppLaunch;
+    ssh?: HostSshAccess;
+}
+/**
+ * Build the target list offered in the connect dialog. `VNC_HOSTS` and
+ * `RDP_HOSTS` are merged into one list; each entry may override its protocol,
+ * so a single list can carry both kinds of target.
+ */
+export declare function parseConfiguredHosts(options: {
+    vncHostsJson?: string;
+    rdpHostsJson?: string;
+    defaultHost?: string;
+    defaultPort?: string;
+    defaultRdpHost?: string;
+    defaultRdpPort?: string;
+}): RemoteHostTarget[];
+/** One allowed network, as a base address and a mask. */
+export interface Subnet {
+    base: number;
+    mask: number;
+}
+/** Dotted-quad to a 32-bit number, or null for anything that is not one. */
+export declare function ipv4ToInt(value: string): number | null;
+/**
+ * The networks this gateway may dial, beyond the machines named in the host
+ * lists. Written as `ALLOWED_SUBNETS`, comma-separated:
+ *
+ *   192.168.8.0/24    a CIDR block
+ *   192.168.8.*       the same thing, written the way people say it
+ *   192.168.8.67      a single address
+ *
+ * This is what lets a terminal open on a machine that was never listed. Keep it
+ * to networks you own: anything inside one can be reached on any port by anyone
+ * who gets past the gateway's login.
+ */
+export declare function parseAllowedSubnets(value?: string): Subnet[];
+/** Whether a dotted-quad address falls inside one of the allowed networks. */
+export declare function hostInAllowedSubnets(host: string, value?: string): boolean;
+/**
+ * Icon path data, shared by the server-rendered login page and the React app.
+ *
+ * Each value is the inside of a 24x24 stroked `<svg>`; the wrapper differs
+ * between the two (a string on the Worker, a component in the browser) but the
+ * geometry should not.
+ */
+export declare const ICON_PATHS: {
+    readonly monitor: '<rect x="2" y="3" width="20" height="14" rx="2"/><path d="M8 21h8M12 17v4"/>';
+    readonly link: '<path d="M9 17H7A5 5 0 0 1 7 7h2M15 7h2a5 5 0 1 1 0 10h-2M8 12h8"/>';
+    readonly power: '<path d="M12 2v10"/><path d="M18.4 6.6a9 9 0 1 1-12.8 0"/>';
+    readonly maximize: '<path d="M8 3H5a2 2 0 0 0-2 2v3M21 8V5a2 2 0 0 0-2-2h-3M3 16v3a2 2 0 0 0 2 2h3M16 21h3a2 2 0 0 0 2-2v-3"/>';
+    readonly minimize: '<path d="M8 3v3a2 2 0 0 1-2 2H3M21 8h-3a2 2 0 0 1-2-2V3M3 16h3a2 2 0 0 1 2 2v3M16 21v-3a2 2 0 0 1 2-2h3"/>';
+    readonly keyboard: '<rect x="2" y="4" width="20" height="16" rx="2"/><path d="M6 8h.01M10 8h.01M14 8h.01M18 8h.01M8 12h.01M12 12h.01M16 12h.01M7 16h10"/>';
+    readonly clipboard: '<rect x="8" y="2" width="8" height="4" rx="1"/><path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2"/>';
+    readonly check: '<path d="m5 13 4 4 10-10"/>';
+    readonly camera: '<path d="M14.5 4h-5L7 7H4a2 2 0 0 0-2 2v9a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2V9a2 2 0 0 0-2-2h-3l-2.5-3z"/><circle cx="12" cy="13" r="3"/>';
+    readonly eye: '<path d="M2 12s3.5-6 10-6 10 6 10 6-3.5 6-10 6S2 12 2 12z"/><circle cx="12" cy="12" r="3"/>';
+    readonly sliders: '<path d="M4 21v-7M4 10V3M12 21v-9M12 8V3M20 21v-5M20 12V3M2 14h4M10 8h4M18 16h4"/>';
+    readonly expand: '<path d="M15 3h6v6M9 21H3v-6M21 3l-7 7M3 21l7-7"/>';
+    readonly shield: '<path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/>';
+    readonly chevron: '<path d="m6 9 6 6 6-6"/>';
+    readonly back: '<path d="m15 18-6-6 6-6"/>';
+    readonly zap: '<path d="M13 2 3 14h9l-1 8 10-12h-9l1-8z"/>';
+    readonly cube: '<path d="M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z"/><path d="m3.3 7 8.7 5 8.7-5M12 22V12"/>';
+    readonly logout: '<path d="M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4M16 17l5-5-5-5M21 12H9"/>';
+    readonly clock: '<circle cx="12" cy="12" r="9"/><path d="M12 7v5l3.5 2"/>';
+    readonly activity: '<path d="M22 12h-4l-3 9L9 3l-3 9H2"/>';
+    readonly transfer: '<path d="m3 16 4 4 4-4M7 20V4M21 8l-4-4-4 4M17 4v16"/>';
+    readonly screen: '<rect x="2" y="5" width="20" height="13" rx="2"/><path d="M7 21h10"/>';
+    readonly command: '<path d="M15 6a3 3 0 1 1 3 3h-3zm0 0v12m0 0a3 3 0 1 0 3-3h-3zM9 6a3 3 0 1 0-3 3h3zm0 0v12m0 0a3 3 0 1 1-3-3h3z"/>';
+    readonly apps: '<rect x="3" y="3" width="7" height="7" rx="1"/><rect x="14" y="3" width="7" height="7" rx="1"/><rect x="3" y="14" width="7" height="7" rx="1"/><rect x="14" y="14" width="7" height="7" rx="1"/>';
+    readonly terminal: '<path d="m4 17 6-6-6-6M12 19h8"/>';
+    readonly folder: '<path d="M3 7h6l2 2h10v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/><path d="M3 7V6a2 2 0 0 1 2-2h4l2 3"/>';
+    readonly close: '<path d="M18 6 6 18M6 6l12 12"/>';
+    readonly sparkles: '<path d="m12 3 1.9 5.1L19 10l-5.1 1.9L12 17l-1.9-5.1L5 10l5.1-1.9L12 3z"/><path d="m19 15 .8 2.2 2.2.8-2.2.8L19 21l-.8-2.2-2.2-.8 2.2-.8z"/>';
+    readonly broom: '<path d="M10 10V4a2 2 0 0 1 4 0v6"/><path d="M6 10h12a2 2 0 0 1 2 2v2H4v-2a2 2 0 0 1 2-2Z"/><path d="m5 14-2 7h18l-2-7M9 18l-1 3M15 18l1 3"/>';
+    readonly panel: '<rect x="3" y="4" width="18" height="16" rx="2"/><path d="M14 4v16"/>';
+    readonly menu: '<path d="M4 7h16M4 12h16M4 17h16"/>';
+    readonly plus: '<path d="M12 5v14M5 12h14"/>';
+    readonly star: '<path d="m12 3 2.9 5.9 6.5.9-4.7 4.6 1.1 6.5L12 17.8 6.2 20.9l1.1-6.5L2.6 9.8l6.5-.9L12 3z"/>';
+    readonly trash: '<path d="M3 6h18M8 6V4a1 1 0 0 1 1-1h6a1 1 0 0 1 1 1v2M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/>';
+};
+export type IconName = keyof typeof ICON_PATHS;
+/** The tab icon: a monitor in Cloudflare orange. */
+export declare const FAVICON_DATA_URI = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23f38020' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Crect x='2' y='3' width='20' height='14' rx='2'/%3E%3Cpath d='M8 21h8M12 17v4'/%3E%3C/svg%3E";
+/**
+ * Control frames the browser and the gateway exchange on the WebSocket that
+ * carries a remote-desktop stream.
+ *
+ * They are plain strings precisely so they can never be confused with the
+ * binary protocol payload flowing in either direction, and both sides import
+ * these same literals so the two halves cannot drift apart.
+ */
+/** Browser -> gateway: "my WebSocket is open, you may start reading the host". */
+export declare const GATEWAY_READY_SIGNAL = "VNC_GATEWAY_READY_v1";
+/**
+ * Browser -> gateway: keep the edge from idling out a silent session.
+ * Cloudflare closes a WebSocket with no traffic in either direction for 100s,
+ * and an untouched desktop transmits nothing at all.
+ */
+export declare const GATEWAY_KEEPALIVE_SIGNAL = "VNC_GATEWAY_KEEPALIVE_v1";
+/**
+ * How often the browser nudges the transport. Well inside the edge's 100s
+ * window, so a session that is merely being looked at is never torn down
+ * without a close frame -- which is what a bare WebSocket 1006 used to mean.
+ */
+export declare const KEEPALIVE_INTERVAL_MS = 25000;
+export declare const MAX_CLOSE_REASON_BYTES = 123;
+/** Whether a live desktop ended for a transient transport reason worth retrying. */
+export declare function isRetryableDisconnect(diagnostic: {
+    close: {
+        code: number;
+        reason: string;
+    } | null;
+    established: boolean;
+}): boolean;
+/** WebSocket close reasons are capped at 123 bytes; trim without splitting a code point. */
+export declare function websocketCloseReason(reason: string): string;
+/** 1005/1006/1015 are reserved and cannot be transmitted in a close frame. */
+export declare function sendableCloseCode(code: number): number;
+/** Normalize any WebSocket message payload to bytes. */
+export declare function messageToBytes(data: unknown): Promise<Uint8Array | null>;