@aiti-ai/grdpwasm 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,162 @@
-# Temporary Holding Version
+# grdpwasm
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[English](README.md) | [中文说明](README.zh-CN.md)
+
+A web-based RDP client built with Go WebAssembly and [grdp](https://github.com/nakagami/grdp).
+Connect to a Windows Remote Desktop server directly from your browser — no plugins required.
+
+> **This is the `aiti-aigrdpwasm` fork** of [nakagami/grdpwasm](https://github.com/nakagami/grdpwasm).
+> It carries a patched `grdp` vendor fork and several feature/fix layers on top of upstream —
+> see [Updates in this fork](#updates-in-this-fork) below.
+> Published to npm as [`@aiti-ai/grdpwasm`](https://www.npmjs.com/package/@aiti-ai/grdpwasm).
+
+> **Availability**: current releases (`0.2.x`) are on the private registry —
+> `npm install @aiti-ai/grdpwasm --registry https://npm.alot.pw`. npmjs.org publication is
+> prepared (`.github/workflows/publish-npm.yml`, two commands once NPM_TOKEN is set);
+> jsDelivr/unpkg CDN links become live at that point. Until then the wasm loads from the
+> same origin when served behind a backend (e.g. aiti-ui-env's rdp-bridge).
+
+## Updates in this fork
+
+### xrdp / gnome-remote-desktop compatibility
+
+- Vendored patched `grdp` fork (`third_party/grdp`): planar codec constant fix, capability
+  advertisement trimmed to what this client can honor (no SURFACE_COMMANDS, no frame
+  marker, no bitmap-cache REV2), NSCodec-capture server-type detection, fullscreen
+  refresh recovery, ECDSA CredSSP key echo, fast-path input PDU padding, clear NLA errors.
+- Automatic EGFX negotiation: connects with GFX first; if the server's actual codec is
+  undecodable (xrdp sends progressive/planar only), it reconnects once in compat mode.
+  GDS/Windows (H.264) connect normally.
+- Lossless WASM transport: inbound messages queue without blocking the JS thread or
+  dropping data (dropping caused stream desync → artifacting/disconnects); bursts are
+  bounded by the bridge's backpressure.
+
+### Frontend
+
+- **fixedTarget mode**: the target host/port is provided by the server (injected
+  `__rdpTarget`) or `?fixedTarget=true`, and can no longer be tampered with from the
+  frontend; standalone mode keeps free-form connection fields.
+- Virtual keyboard (programmer layout), shortcut bar, native system-keyboard proxy,
+  X11/RFB keysym helpers — shared, host-agnostic components.
+- xrdp color-cursor mitigation: cursors whose AND mask makes them fully opaque render
+  as black blocks; they are detected (≥95% opaque ratio) and discarded.
+
+### Packaging & delivery (@aiti-ai/grdpwasm)
+
+- Published as an npm package. The tarball ships `main.wasm` (that's what jsDelivr/unpkg
+  serve from), but `postinstall` removes the local copy after install — at runtime the
+  page race-downloads the wasm from CDNs via [justget](https://github.com/justdb/justget)
+  with same-origin fallback (override: `?wasm=<url>` or `localStorage['grdpwasm.wasmUrl']`).
+- Server-side fallback for embedders: a backend helper (`ensureRdpWasm` pattern) can
+  pre-fetch the wasm into a cache dir so the static server always has one to serve.
+
+## Architecture
+
+```
+Browser (WASM) ──WebSocket──► proxy (Go) ──TCP──► RDP Server
+```
+
+Because browsers cannot open raw TCP sockets, a lightweight Go proxy server bridges
+WebSocket connections from the browser to the RDP server's TCP port.
+
+## Requirements
+
+- Go 1.24 or later
+- A reachable RDP server (Windows or any RDP-compatible host)
+
+## Build
+
+```bash
+git clone https://github.com/nakagami/grdpwasm.git
+cd grdpwasm
+make all
+```
+
+`make all` produces:
+
+| Output | Description |
+|---|---|
+| `static/main.wasm` | Go WASM binary (runs in the browser) |
+| `static/wasm_exec.js` | Go runtime JS support file |
+| `proxy/proxy` | WebSocket-to-TCP proxy + static file server |
+
+## Run
+
+```bash
+make serve
+# or equivalently:
+./proxy/proxy -listen :8080 -static static
+```
+
+Then open **http://localhost:8080** in your browser.
+
+### Proxy options
+
+| Flag | Default | Description |
+|---|---|---|
+| `-listen` | `:8080` | Address and port to listen on |
+| `-static` | `static` | Directory to serve static files from |
+
+## Usage
+
+1. Open `http://localhost:8080` in a browser.
+2. Fill in the connection form:
+   - **Host** — hostname or IP address of the RDP server
+   - **Port** — RDP port (default `3389`)
+   - **Domain** — Windows domain (leave blank for local accounts)
+   - **User** — username
+   - **Password** — password
+   - **Width / Height** — initial desktop resolution
+3. Click **Connect**.
+4. The remote desktop appears in the canvas. Click the canvas to capture keyboard focus.
+5. Click **Disconnect** to end the session.
+
+## Keyboard & Mouse
+
+All standard keyboard input is forwarded to the remote desktop via RDP scan codes.
+Mouse move, button clicks, and scroll wheel are fully supported.
+
+> **Note:** The browser tab must have focus for keyboard events to be forwarded.
+> Click inside the canvas area if keys stop responding.
+
+## Audio
+
+Remote audio is streamed via RDPSND and played through the browser's Web Audio API
+(PCM 44100 Hz, stereo, 16-bit signed little-endian).
+
+## Security notes
+
+- The proxy accepts connections from any origin. Run it only on a trusted network
+  or add authentication before exposing it to the internet.
+- Credentials are transmitted from the browser to the proxy over WebSocket.
+  Use HTTPS/WSS (put the proxy behind a TLS-terminating reverse proxy such as
+  nginx or Caddy) when accessing it over an untrusted network.
+
+## Development
+
+```
+npm install     # install JS dependencies (justget, esbuild)
+make wasm       # rebuild only the WASM binary
+make proxy      # rebuild only the proxy server
+make wasm_exec  # refresh wasm_exec.js from the local Go toolchain
+npm run build:vendor  # rebuild static/vendor/justget.browser.js from the installed justget
+make clean      # remove all build artifacts
+```
+
+## npm package
+
+Publish the browser assets as `@aiti-ai/grdpwasm`. Consumers get everything except
+`main.wasm` — the page fetches it from CDN at runtime.
+
+```bash
+npm run build:vendor   # bundle justget/browser into static/vendor/
+make all               # build main.wasm + wasm_exec.js + proxy
+npm publish            # prepack syncs the version into index.html; tarball ships the wasm
+```
+
+Consumers get `static/` (html/js/vendor) without `main.wasm` — the page fetches it
+from CDN at runtime. Set `GRDPWASM_KEEP_WASM=1` before install to keep the local copy.
+
+## License
+
+GPLv3 — see [grdp LICENSE](https://github.com/nakagami/grdp/blob/master/LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,145 @@
+# grdpwasm
+
+[English](README.md) | 中文说明
+
+基于 Go WebAssembly 与 [grdp](https://github.com/nakagami/grdp) 构建的网页版 RDP 客户端。
+在浏览器里直连 Windows 远程桌面——无需任何插件。
+
+> **本仓库是 [nakagami/grdpwasm](https://github.com/nakagami/grdpwasm) 的 `aiti-aigrdpwasm` fork**，
+> 在上游之上带有一个补丁版 grdp vendor fork 及多层功能/修复，详见下方
+> [本 fork 更新说明](#本-fork-更新说明)。
+> 已发布为 npm 包 [`@aiti-ai/grdpwasm`](https://www.npmjs.com/package/@aiti-ai/grdpwasm)。
+
+## 本 fork 更新说明
+
+### xrdp / gnome-remote-desktop 兼容
+
+- 内置补丁版 grdp fork（`third_party/grdp`）：planar codec 常量修复；能力集广播裁剪到本客户端能真正
+  支持的范围（不广播 SURFACE_COMMANDS、frame marker、bitmap-cache REV2）；NSCodec 捕获检测用于
+  服务器类型判别；全屏刷新恢复初始画面损伤；ECDSA CredSSP 公钥回显；fast-path 输入 PDU 8 字节对齐；
+  NLA 失败返回明确错误信息。
+- EGFX 自动协商：先带 GFX 连接；若服务器实际编码本客户端无法解码（xrdp 只发 progressive/planar），
+  自动以兼容模式重连一次。GDS/Windows（H.264）正常连接，无感知。
+- 无损 WASM 传输层：收包队列既不阻塞 JS 线程也不丢消息（丢包 = 流失步 → 花屏/断连）；突发期内存
+  由桥的背压机制约束有界。
+
+### 前端
+
+- **fixedTarget 模式**：目标 host/port 由服务端提供（注入 `__rdpTarget`）或经 `?fixedTarget=true` 传入，
+  前端不可篡改；standalone 模式保留自由连接表单。
+- 虚拟键盘（程序员布局）、快捷键条、原生系统键盘代理、X11/RFB keysym 工具——载体无关公共组件。
+- xrdp 彩色光标缓解：AND 掩码导致整个矩形全不透明的光标会渲染成黑块，检测到（不透明占比 ≥95%）即丢弃。
+
+### 打包与分发（@aiti-ai/grdpwasm）
+
+- 已发布为 npm 包。tarball 里带 `main.wasm`（jsDelivr/unpkg 分发的源头），但 postinstall 在安装后即删除
+  本地副本——运行时页面经 [justget](https://github.com/justdb/justget) 从 CDN 竞速下载 wasm，同源兜底
+  （覆盖方式：`?wasm=<url>` 或 `localStorage['grdpwasm.wasmUrl']`）。
+- 面向嵌入方的服务端兜底：后端可按 `ensureRdpWasm` 模式把 wasm 预取到缓存目录，静态服务随时有得 serve。
+
+## 架构
+
+```
+浏览器 (WASM) ──WebSocket──► proxy (Go) ──TCP──► RDP 服务器
+```
+
+浏览器无法直接开 TCP socket，由一个轻量 Go 代理把浏览器的 WebSocket 连接桥接到
+RDP 服务器的 TCP 端口。
+
+## 环境要求
+
+- Go 1.24 或更高
+- 一台可达的 RDP 服务器（Windows 或任何 RDP 兼容主机）
+
+## 构建
+
+```bash
+git clone https://github.com/nakagami/grdpwasm.git
+cd grdpwasm
+make all
+```
+
+`make all` 产物：
+
+| 产物 | 说明 |
+|---|---|
+| `static/main.wasm` | Go WASM 二进制（跑在浏览器里） |
+| `static/wasm_exec.js` | Go 运行时 JS 支撑文件 |
+| `proxy/proxy` | WebSocket↔TCP 代理 + 静态文件服务 |
+
+## 运行
+
+```bash
+make serve
+# 或者等价手动启动：
+./proxy/proxy -listen :8080 -static static
+```
+
+然后用浏览器打开 **http://localhost:8080**。
+
+### 代理参数
+
+| 参数 | 默认值 | 说明 |
+|---|---|---|
+| `-listen` | `:8080` | 监听地址与端口 |
+| `-static` | `static` | 静态文件目录 |
+
+## 使用
+
+1. 浏览器打开 `http://localhost:8080`。
+2. 填写连接表单：
+   - **Host** — RDP 服务器主机名或 IP
+   - **Port** — RDP 端口（默认 `3389`）
+   - **Domain** — Windows 域（本地账号留空）
+   - **User** — 用户名
+   - **Password** — 密码
+   - **Width / Height** — 初始桌面分辨率
+3. 点击 **Connect**。
+4. 远程桌面出现在画布里；点击画布捕获键盘焦点。
+5. 点击 **Disconnect** 结束会话。
+
+## 键盘与鼠标
+
+所有标准键盘输入经 RDP 扫描码转发到远程桌面。鼠标移动、按键点击、滚轮完整支持。
+
+> **注意：** 浏览器标签页必须持有焦点，键盘事件才会转发。按键无响应时请点击画布区域。
+
+## 音频
+
+远程音频经 RDPSND 流式传输，通过浏览器 Web Audio API 播放
+（PCM 44100 Hz、立体声、16 位有符号小端）。
+
+## 安全须知
+
+- 代理接受任意来源的连接。请只在可信网络运行，或先加认证再暴露到公网。
+- 凭据经 WebSocket 从浏览器传到代理。跨不可信网络访问时请使用 HTTPS/WSS
+  （把代理放在 nginx/Caddy 等 TLS 终结反代之后）。
+
+## 开发
+
+```
+npm install     # 安装 JS 依赖（justget、esbuild）
+make wasm       # 只重编 WASM 二进制
+make proxy      # 只重编代理服务
+make wasm_exec  # 用本地 Go 工具链刷新 wasm_exec.js
+npm run build:vendor  # 从已安装的 justget 重编 static/vendor/justget.browser.js
+make clean      # 清理全部构建产物
+```
+
+## npm 包
+
+把前端资产发布为 `@aiti-ai/grdpwasm`。消费者装到除 `main.wasm` 外的全部文件——
+页面运行时自行从 CDN 拉取。
+
+```bash
+npm run build:vendor   # 把 justget/browser 打包进 static/vendor/
+make all               # 构建 main.wasm + wasm_exec.js + proxy
+npm publish            # prepack 会把版本号同步进 index.html；tarball 带 wasm
+```
+
+安装方拿到的是不含 `main.wasm` 的 `static/`（html/js/vendor）——页面运行时从 CDN 拉取。
+如需保留本地副本，安装前设置 `GRDPWASM_KEEP_WASM=1`。
+
+## 许可证
+
+GPLv3 —— 见 [grdp LICENSE](https://github.com/nakagami/grdp/blob/master/LICENSE)。

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@aiti-ai/grdpwasm",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "Web-based RDP client (Go WASM + WebSocket proxy) — browser assets; main.wasm fetched from CDN at runtime via justget",
+  "license": "GPL-3.0",
+  "homepage": "https://github.com/aiti-ai/aiti-aigrdpwasm#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aiti-ai/aiti-aigrdpwasm.git"
+  },
+  "files": [
+    "static/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prepack": "node scripts/sync-version.mjs",
+    "postinstall": "node scripts/postinstall.mjs",
+    "build:vendor": "esbuild node_modules/justget/dist/browser/index.js --bundle --format=iife --global-name=justget --minify --outfile=static/vendor/justget.browser.js"
+  },
+  "dependencies": {
+    "justget": "^0.2.4"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2"
+  },
+  "bugs": "https://github.com/aiti-ai/aiti-aigrdpwasm/issues"
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,28 @@
+/**
+ * postinstall: remove main.wasm (~11MB) from the installed copy.
+ *
+ * The npm tarball ships the wasm (that's what jsDelivr/unpkg serve from), but at
+ * runtime the page race-downloads it from CDNs via justget — no need to keep a
+ * local copy, so delete it right after install to save disk.
+ *
+ * Skipped when:
+ *   - inside a source checkout (.git exists): running `npm install` in the repo
+ *     triggers this lifecycle hook too; dev build artifacts must survive;
+ *   - GRDPWASM_KEEP_WASM=1 is set explicitly.
+ */
+import { existsSync, rmSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const wasm = join(root, "static", "main.wasm");
+
+if (process.env.GRDPWASM_KEEP_WASM === "1") {
+  console.log("[grdpwasm] GRDPWASM_KEEP_WASM=1, keep static/main.wasm");
+} else if (existsSync(join(root, ".git"))) {
+  console.log("[grdpwasm] source checkout detected (.git), keep static/main.wasm");
+} else if (existsSync(wasm)) {
+  const mb = (statSync(wasm).size / 1048576).toFixed(1);
+  rmSync(wasm);
+  console.log(`[grdpwasm] removed static/main.wasm (${mb} MB) - runtime fetches from CDN`);
+}

package/scripts/sync-version.mjs

@@ -0,0 +1,23 @@
+/**
+ * prepack: sync the package.json version into PKG_VERSION inside
+ * static/index.html so the runtime CDN URLs always match the published version.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const { version } = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+
+const html = join(root, "static", "index.html");
+const src = readFileSync(html, "utf8");
+if (!/const PKG_VERSION = "[^"]*";/.test(src)) {
+  console.error("[grdpwasm] PKG_VERSION placeholder not found in index.html");
+  process.exit(1);
+}
+const next = src.replace(
+  /const PKG_VERSION = "[^"]*";/,
+  `const PKG_VERSION = "${version}";`
+);
+if (next !== src) writeFileSync(html, next);
+console.log(`[grdpwasm] index.html PKG_VERSION -> ${version}`);