ai-remote 0.4.6 → 0.4.8

package/README.md

@@ -26,6 +26,11 @@ npx ai-remote key Enter
 # Run commands in the remote terminal over SSH:
 npx ai-remote exec "dir"
 
+# A host with no desktop -- a Linux box, a Mac, a container -- is a terminal
+# session. Keys are used before passwords, so this usually needs nothing set:
+npx ai-remote open 192.168.1.60 --ssh -u deploy
+npx ai-remote exec "systemctl status nginx"
+
 # Let it go when you are done -- nothing closes on its own:
 npx ai-remote close
 ```
@@ -34,6 +39,8 @@ npx ai-remote close
 
 ```
   ai-remote open <host[:port]>       connect, show a window, and stay open
+  ai-remote open <host> --ssh        a terminal only: no desktop, no RDP
+  ai-remote open <host> --vnc        a screen over VNC (implied by port 5900)
 
   ai-remote shot                     screenshot the desktop
   ai-remote click X,Y                click, --button right|middle, --double
@@ -46,6 +53,8 @@ npx ai-remote close
   ai-remote view --close             close the window, session keeps running
   ai-remote status                   what the session is doing
   ai-remote list                     every session that is open
+  ai-remote saved                    machines with a password kept
+  ai-remote forget [<host[:port]>]   throw one away; --all throws all
   ai-remote close                    close it; --all closes every session
   ai-remote probe [<host[:port]>]    is anything listening?
 ```
@@ -70,9 +79,80 @@ npx ai-remote close --all
 it answers whether a session could be opened at all; with no address it probes
 the current session's host.
 
+### A screen over VNC
+
+Macs, Linux desktops and anything else running a VNC server are opened with
+`--vnc`, or just by naming port 5900. Everything else is the same as RDP -- the
+same window, the same `shot`, `click`, `type`, `key` and `do`, the same session
+that stays open until it is closed:
+
+```bash
+AI_REMOTE_PASSWORD=... npx ai-remote open 192.168.1.70 --vnc -u alex
+npx ai-remote shot -o screen.png
+npx ai-remote click 640,400
+```
+
+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
+every host implements. Raw is bandwidth-hungry by design; on a LAN a 1080p
+desktop is fine, over a slow link it will feel it.
+
+A session that is already open can be given a screen without being reopened,
+which is the point of `vnc` taking no host:
+
+```bash
+npx ai-remote open 192.168.1.70 --ssh -u alex    # a terminal
+npx ai-remote vnc                                # ...and now a screen too
+npx ai-remote exec "uptime"                      # both, one session
+```
+
+### Terminal-only sessions
+
+`--ssh` opens a session that is a terminal and nothing else: no RDP handshake,
+no framebuffer, and a window that is all terminal. Port 22 implies it, so
+`open box:22` and `open box --ssh` are the same thing.
+
+`exec`, `shell`, `status`, `view` and `close` work as they always do. The
+commands about pixels -- `shot`, `click`, `type`, `key`, `do` -- say there is no
+desktop rather than failing obscurely.
+
+The session lasts until `close`. If the host drops the terminal -- an idle
+timeout on its side, or an `exit` typed into the window -- the session stays
+where it is and the next command opens another one; `status` says `disconnected`
+in between.
+
+```bash
+npx ai-remote open 192.168.1.60 --ssh -u deploy    # a terminal window
+npx ai-remote exec "uname -a"
+npx ai-remote shell                                # Ctrl-] to leave
+```
+
+### Signing in
+
+Keys first, then a password.
+
+With no `--identity`, ssh-agent is asked for whatever it is holding, and
+`~/.ssh/id_ed25519`, `id_ecdsa` and `id_rsa` are read if they have no
+passphrase -- so a host that already takes your key needs nothing set at all.
+Ed25519, ECDSA and RSA keys are supported, in OpenSSH's own format as well as
+PKCS#8 and the older PEM containers.
+
+```bash
+npx ai-remote open box --ssh -u deploy                          # agent + ~/.ssh
+npx ai-remote open box --ssh -u deploy -i ~/.ssh/deploy_ed25519 # one named key
+ssh-add ~/.ssh/id_ed25519                                       # a key with a passphrase
+```
+
+A key with a passphrase is not read off disk: add it to ssh-agent, which is
+where a decrypted key belongs, and it is offered from there.
+
 ### Options for `open`
 
+- `--ssh`: A terminal session only, with no desktop (implied by port 22).
+- `--vnc`: A screen over VNC rather than RDP (implied by port 5900).
 - `-u, --user NAME`: Account name on the host.
+- `-i, --identity FILE`: A private key to sign in with. Repeatable.
 - `-d, --domain NAME`: Windows domain or computer name.
 - `--session NAME`: Name this session (default: `host_port`).
 - `--ssh-user NAME`: Account for the SSH terminal (defaults to `--user`).
@@ -82,6 +162,7 @@ the current session's host.
 - `--idle MINUTES`: Close an unused session (default: 0, never).
 - `--headless` / `--no-view`: Run headless without opening the viewer window.
 - `--no-reuse`: A second session beside one that is already open.
+- `--save`: Keep the password for next time, once it has worked.
 
 ### Options for the rest
 
@@ -90,8 +171,9 @@ the current session's host.
 - `--max-edge N`: Shrink a screenshot to fit N.
 - `--json`: Output machine-readable JSON results on stdout.
 
-The password comes from `AI_REMOTE_PASSWORD` (or `REMOTECTL_PASSWORD`). There is
-no `--password` flag: a command line is visible to every process on the machine.
+The password, where one is wanted, comes from `AI_REMOTE_PASSWORD` (or
+`REMOTECTL_PASSWORD`). There is no `--password` flag: a command line is visible
+to every process on the machine.
 
 ---
 

package/SKILL.md

@@ -126,6 +126,48 @@ leave) — that one is for a human, not for an agent, because it never returns.
 Reach for the GUI when the task is genuinely graphical. Reach for `exec` for
 anything a shell can do.
 
+## A Mac, or anything else that speaks VNC
+
+`--vnc` opens the screen over VNC instead of RDP; port 5900 implies it. Every
+desktop command works exactly as it does over RDP -- there is nothing
+protocol-specific to remember:
+
+```bash
+export AI_REMOTE_PASSWORD=...        # the VNC password, or the macOS account's
+npx ai-remote open 192.168.1.70 --vnc -u alex
+npx ai-remote shot -o screen.png
+npx ai-remote click 640,400
+```
+
+A session that is already open gets a screen with `ai-remote vnc`, which takes
+no host because the session already knows the machine. That is the way to give a
+terminal session a desktop without closing it.
+
+## A host with no desktop
+
+`--ssh` opens a session that is a terminal and nothing else — no RDP handshake
+to wait for, and none to fail. Port 22 implies it.
+
+```bash
+npx ai-remote open 192.168.1.60 --ssh -u deploy
+npx ai-remote exec "systemctl status nginx"
+npx ai-remote close
+```
+
+`exec`, `shell`, `status`, `view` and `close` work as usual; `shot`, `click`,
+`type`, `key` and `do` say there is no desktop, because there is not one.
+
+The session lasts until `close`, not until the terminal does: if the host drops
+the connection, the next `exec` opens another one and the session name, the
+account and the keys stay put.
+
+**Keys before passwords.** With no `--identity`, ssh-agent is asked for what it
+holds and `~/.ssh/id_ed25519`, `id_ecdsa` and `id_rsa` are read when they have
+no passphrase — so a host that already takes your key needs no environment
+variable at all. `-i FILE` names a key instead, and repeats. A key with a
+passphrase is never read off disk: `ssh-add` it, and it is offered from the
+agent.
+
 ## Sessions
 
 The session opened last is the one commands drive. With several open, name them:
@@ -192,7 +234,10 @@ start a session implicitly, because they have no host to start one with.
 **Credentials rejected (11), or a session that stops before it is ready.** —
 Almost always `AI_REMOTE_PASSWORD` missing from *this* shell. It is deliberately
 not a flag, and it does not carry across terminals; export it again. `open` says
-so explicitly when it sees the host ask for NLA and finds no password.
+so explicitly when it sees the host ask for NLA and finds no password. Over SSH
+the other half of the answer is a key: `ssh-add ~/.ssh/id_ed25519`, or
+`-i FILE`. The session's log names every key it offered and every key it passed
+over, and why.
 
 **Unreachable (10).** — `ai-remote probe <host>` is the one command besides
 `open` that still takes an address: it answers whether anything is listening
@@ -213,6 +258,9 @@ what `status` reports rather than what you asked for.
 ```bash
 export AI_REMOTE_PASSWORD=...
 npx ai-remote open HOST[:PORT] -u USER [-d DOMAIN] [--session NAME] [--headless] [--watch-only]
+npx ai-remote open HOST --ssh -u USER [-i ~/.ssh/id_ed25519]      # a terminal, no desktop
+npx ai-remote open HOST --vnc -u USER                             # a screen over VNC
+npx ai-remote vnc                                                 # ...or add one to this session
 npx ai-remote shot [-o FILE] [--max-edge N] [--json]
 npx ai-remote click X,Y [--button right|middle] [--double]
 npx ai-remote type "text"

package/dist/apple-dh.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Apple's Diffie-Hellman, which is how macOS Screen Sharing signs somebody in.
+ *
+ * Security type 30: the host sends a generator, a prime and its public value;
+ * the client agrees a secret, keys AES with it, and sends back the account and
+ * password encrypted under that key followed by its own public value. None of
+ * it is negotiable -- the order, the widths and the padding are Apple's, and
+ * noVNC's `_negotiateARDAuth` is the reference every implementation follows.
+ *
+ * An entrypoint of its own because two very different programs need it: the
+ * Worker performs this exchange on behalf of a browser, and the CLI performs it
+ * for itself. One wire format, one implementation -- there is no version of
+ * this that is safe to have two of.
+ *
+ * Node's crypto rather than Web Crypto, because the exchange needs MD5 and
+ * single-block AES-ECB and Web Crypto has neither. Both callers run somewhere
+ * that has it: the CLI is Node, and the Worker runs with `nodejs_compat`.
+ */
+/**
+ * The answer to a host's key exchange.
+ *
+ * `params` is what the host sent: two bytes of generator, two of key length,
+ * then the prime and the host's public value at that length -- 1028 bytes on a
+ * Mac. What comes back is the encrypted credentials first and this end's public
+ * value after, which is 640 bytes for the same Mac.
+ */
+export declare function appleDhResponse(params: Uint8Array, username: string, password: string): Uint8Array;

package/dist/apple-dh.js

@@ -0,0 +1 @@
+import{createCipheriv as B,createHash as p,randomBytes as w}from"node:crypto";var u=(e,i,n)=>{let r=1n,t=e%n,o=i;for(;o>0n;)o%2n===1n&&(r=r*t%n),o/=2n,t=t*t%n;return r},s=e=>e.reduce((i,n)=>i<<8n|BigInt(n),0n);function l(e,i){let n=new Uint8Array(i),r=e;for(let t=i-1;t>=0&&r>0n;t--)n[t]=Number(r&0xffn),r>>=8n;return n}function U(e,i,n){if(e.length<4)throw new Error(`Apple DH parameters are too short: ${e.length} bytes.`);let r=BigInt(e[0]<<8|e[1]),t=e[2]<<8|e[3];if(t===0||e.length<4+t*2)throw new Error(`Apple DH parameters are truncated: a ${t}-byte prime needs ${4+t*2} bytes, and ${e.length} arrived.`);let o=s(e.subarray(4,4+t)),y=s(e.subarray(4+t,4+t*2)),a=s(w(t)),d=l(u(r,a,o),t),g=l(u(y,a,o),t),b=p("md5").update(g).digest(),c=Buffer.alloc(128,0);Buffer.from(i,"utf8").subarray(0,63).copy(c,0),Buffer.from(n,"utf8").subarray(0,63).copy(c,64);let f=B("aes-128-ecb",b,Buffer.alloc(0));f.setAutoPadding(!1);let h=Buffer.concat([f.update(c),f.final()]);return new Uint8Array(Buffer.concat([h,Buffer.from(d)]))}export{U as appleDhResponse};