@eduwork/dsh-remote-access 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 变更记录 / Changelog
 
+## 0.1.1 — 2026-10-24
+
+- 随 npm 包提供中英文自托管中继部署指南：固定版本启动、Key、HTTPS/Nginx、路径前缀、systemd、OIDC、iframe 与排错。
+- 澄清同源集成的信任范围，以及直接终端接口与 Agent 权限的区别；运行代码与协议不变。
+
+- Include bilingual relay deployment guides covering pinned npm startup, access keys, HTTPS/Nginx, path prefixes, systemd, OIDC, iframe integration and troubleshooting.
+- Clarify same-origin trust boundaries and direct terminal APIs versus Agent permissions; runtime code and protocol are unchanged.
+
 ## 0.1.0 — 2026-10-23
 
 - 首个版本：在手机或其他电脑的浏览器中使用本机的 DSH，包含 DSH 插件与设置页、可自托管的中继和网页客户端。

package/README.md

@@ -16,13 +16,15 @@
 需要 Node.js 24.22.1 或更新版本，以及为中继域名提供 HTTPS 并转发 WebSocket 的反向代理。
 
 ```sh
-RELAY_URL=https://remote.example.edu RELAY_ACCESS_KEYS=key-1,key-2 \
-  npx -p @eduwork/dsh-remote-access eduwork-remote-relay
+RELAY_URL=https://remote.example.edu/ RELAY_ACCESS_KEYS=替换成随机Key \
+  npx --yes --package=@eduwork/dsh-remote-access@0.1.1 eduwork-remote-relay
 ```
 
 `RELAY_URL` 是用户访问中继的公开地址；`RELAY_ACCESS_KEYS` 是发给电脑主人的接入密钥，多个用逗号分隔。中继默认监听 `127.0.0.1:8787`，可用 `HOST`、`PORT` 修改；`<RELAY_URL>healthz` 返回 `ok`，可用于监控。
 
-中继也可以和其他网站共用域名，放在单独的路径下，例如 `RELAY_URL=https://example.edu/eduwork-remote/`。反向代理须按原路径转发、不去掉这段前缀；中继的网页、Service Worker 和连接都只在这个路径下。电脑上填写同一个地址。共用域名有安全风险（见[安全](#安全)），只适合同一域名下没有需要登录的网站时使用；同一域名下若有作用于整个域名的 Service Worker，还须让它放过这段路径。
+完整的 [中继部署指南](docs/DEPLOYMENT.md) 包含 Key 生成、Windows PowerShell 命令、HTTPS/Nginx、路径前缀、systemd 常驻运行、机构登录和 iframe 集成，以及启动后的验证与排错步骤。
+
+中继也可以部署在同域的单独路径，例如 `RELAY_URL=https://example.edu/eduwork-remote/`。反向代理须保留此前缀，电脑上填写同一个完整地址。同域路径不隔离浏览器权限，部署者须确认站点与被配对电脑处于可接受的共同信任范围（见[安全](#安全)）；作用于整个站点的 Service Worker 还须放过这段路径。
 
 学校或企业也可以让成员凭自己的登录使用中继，不必逐个发接入密钥：`RELAY_OIDC_ISSUER` 填机构 OpenID Connect 登录的 issuer（例如 `https://sso.example.edu`），`RELAY_OIDC_CLIENT_IDS` 填桌面应用在该登录中的 client ID，多个用逗号分隔。电脑以登录得到的 ID Token 注册，中继用 issuer 公布的公钥验证，只记录用户标识，不记录 Token。Token 到期前电脑会自动换新的；到期仍未换新时，中继断开这台电脑现有的远程连接。机构登录失效、需要重新登录时，电脑停止连接中继，设置页提示重新登录。两种方式可以同时启用。
 
@@ -56,11 +58,11 @@ dsh plugin --profile web add @eduwork/dsh-remote-access
 
 ## 远程设备能做什么
 
-可以选择已有工作区，查看或新建会话，继续和取消任务，审批或回答提问，查看和下载结果；在 EduWork 中还可以使用 Studio 成果和日历。
+可以选择已有工作区，查看或新建会话，继续和取消任务，审批或回答提问，查看和下载结果；宿主已安装相应插件时，还可以使用 Studio 成果和日历。
 
 手机上看到的就是 DSH 自己的界面，只按窄屏做了调整：会话列表（工作区目录、搜索、新会话等）从左上角打开并铺满屏幕，选中会话或面板后自动收起；设置同样铺满屏幕，各分区排成一行标签，在远程设备上只能查看；对话中的耗时、重试、审批和提问与电脑上一致。
 
-不能在电脑上打开窗口、程序或发出通知，不能注册或删除工作区，不能修改设置或管理账号、插件、凭据、技能和记忆，不能使用终端或执行代码，也不能管理远程访问本身。完整清单见 [src/gate/gate.ts](src/gate/gate.ts)，未列出的接口一律拒绝。
+远端不能直接调用打开本机窗口、程序或发出通知的接口，不能注册或删除工作区、修改设置、管理账号、插件、凭据、技能、记忆或远程访问本身，也不能直接使用终端与代码执行接口。**通过 Agent 发起的任务仍可能执行命令，沿用该会话的权限与审批规则**；禁止直接调用终端接口不等于禁止 Agent 使用工具。完整清单见 [src/gate/gate.ts](src/gate/gate.ts)，未列出的接口一律拒绝。
 
 ## 安全
 
@@ -68,8 +70,8 @@ dsh plugin --profile web add @eduwork/dsh-remote-access
 - 设备密钥由浏览器生成且不可导出，电脑只保存设备公钥。每次连接都要用设备密钥签名。
 - 接入密钥和机构登录只决定谁能使用这台中继，不能用来连接别人的电脑。接入密钥保存在 DSH 的凭据里（`EDUWORK_REMOTE_ACCESS_KEY`），不写进插件设置；机构登录的 ID Token 只发给发行版预置的中继，设置页不能更改这个地址。
 - 手机上打开的网页由中继提供，部署中继的人可以修改它。请只使用你信任的中继。
-- 手机上显示的 DSH 界面由所连的电脑提供，与中继的网页运行在同一个域名下，而浏览器只按域名隔离数据。因此一台电脑提供的界面，能使用此浏览器与其他电脑的配对去连接它们。请只与自己的电脑配对。
-- 同理，中继与其他网站共用域名时，那些网站的脚本能使用这里的配对连接电脑；任何一台被配对的电脑提供的界面，也能以用户的身份访问那些网站、读取它们保存在浏览器里的数据。请为中继使用单独的域名（例如子域名），不要与登录服务或其他需要登录的网站共用。
+- 手机上显示的 DSH 界面由所连的电脑提供，与中继网页同源。浏览器按来源（协议、主机、端口）而非路径隔离数据，因此一台电脑提供的界面能使用此浏览器与其他电脑的配对去连接它们。请只与自己的电脑配对。
+- 同理，中继与其他网站同源时，那些网站的脚本能使用这里的配对连接电脑；任何一台被配对的电脑提供的界面，也能以用户的身份访问那些网站及脚本可访问的浏览器数据。独立域名能缩小信任范围；若选择同域路径集成，需要接受这项共同信任边界，路径前缀和普通 iframe 均不提供隔离。
 - 允许其他页面嵌入中继的网页后，那些页面能把它显示在自己的页面里并加以遮挡，诱导用户点击（例如批准命令）。只允许你信任的页面嵌入。
 
 协议细节见[协议文档](docs/PROTOCOL.md)。

package/README_EN.md

@@ -16,13 +16,15 @@ The package has two parts:
 You need Node.js 24.22.1 or later and a reverse proxy that serves HTTPS for the relay's domain and forwards WebSockets.
 
 ```sh
-RELAY_URL=https://remote.example.edu RELAY_ACCESS_KEYS=key-1,key-2 \
-  npx -p @eduwork/dsh-remote-access eduwork-remote-relay
+RELAY_URL=https://remote.example.edu/ RELAY_ACCESS_KEYS=replace-with-a-random-key \
+  npx --yes --package=@eduwork/dsh-remote-access@0.1.1 eduwork-remote-relay
 ```
 
 `RELAY_URL` is the public address users reach the relay at; `RELAY_ACCESS_KEYS` are the comma-separated access keys you give to computer owners. The relay listens on `127.0.0.1:8787` by default; change it with `HOST` and `PORT`. `<RELAY_URL>healthz` answers `ok` for monitoring.
 
-The relay can also share a domain with other sites under a path of its own, for example `RELAY_URL=https://example.edu/eduwork-remote/`. The reverse proxy must pass the path on unchanged, keeping that prefix; the relay's pages, Service Worker and connections all stay below it. Enter the same address on the computer. Sharing a domain has security risks (see [Security](#security)): do it only when no site on that domain needs signing in to, and if a Service Worker there covers the whole domain, make it leave this path alone.
+The [relay deployment guide](docs/DEPLOYMENT_EN.md) covers key generation, Windows PowerShell commands, HTTPS/Nginx, path prefixes, persistent systemd operation, organization sign-in, iframe integration, verification and troubleshooting.
+
+The relay can also share a domain under its own path, such as `RELAY_URL=https://example.edu/eduwork-remote/`. Preserve the prefix in proxy requests and enter the same complete URL on the computer. Paths do not isolate browser privileges: the operator must accept the shared trust boundary between the site's applications and paired computers (see [Security](#security)). A site-wide Service Worker must also leave this path alone.
 
 A school or company can instead let its members use the relay with their own sign-in, without handing out access keys: set `RELAY_OIDC_ISSUER` to the issuer of the organization's OpenID Connect sign-in (for example `https://sso.example.edu`) and `RELAY_OIDC_CLIENT_IDS` to the desktop application's client IDs in it, separated by commas. Computers register with the ID Token their sign-in issued; the relay checks it against the keys the issuer publishes and keeps only the user's identifier, never the token. Computers switch to a new token before theirs expires; if one expires without being renewed, the relay ends that computer's remote connections. When the organization sign-in has lapsed and needs signing in again, the computer stops connecting to the relay and the settings page asks the user to sign in again. Both ways can be enabled together.
 
@@ -56,11 +58,11 @@ Choose "Remove" under "Paired devices" on the computer to disconnect a device at
 
 ## What remote devices can do
 
-They can choose an existing workspace, view and start conversations, continue and cancel tasks, approve or answer questions, and view and download results; in EduWork they can also use Studio results and the calendar.
+They can choose an existing workspace, view and start conversations, continue and cancel tasks, approve or answer questions, and view and download results. Studio results and the calendar are also available when those plugins are installed on the host.
 
 A phone shows DSH's own interface, only fitted to the narrow screen: the session list (workspace folders, search, new session and so on) opens full screen from the top-left corner and closes once you pick a session or a panel; settings also fill the screen, with the sections as a row of tabs, and are view only on remote devices; conversations show durations, retries, approvals and questions as on the computer.
 
-They cannot open windows or programs or show notifications on the computer, register or remove workspaces, change settings or manage accounts, plugins, credentials, skills or memories, use terminals or run code, or manage remote access itself. The full list is in [src/gate/gate.ts](src/gate/gate.ts); anything not listed is refused.
+Remote devices cannot directly call APIs that open local windows or programs or show notifications, register or remove workspaces, change settings, manage accounts, plugins, credentials, skills, memories or remote access, or access terminal and code-execution APIs. **Tasks submitted through the Agent can still execute commands under the session's permission and approval rules**; blocking direct terminal APIs does not disable Agent tools. The full list is in [src/gate/gate.ts](src/gate/gate.ts); anything not listed is refused.
 
 ## Security
 
@@ -68,8 +70,8 @@ They cannot open windows or programs or show notifications on the computer, regi
 - The browser generates the device key as non-extractable; the computer stores only its public key. Every connection is signed with the device key.
 - An access key or an organization sign-in only decides who may use the relay; neither can be used to connect to someone else's computer. The access key is kept in DSH's credentials (`EDUWORK_REMOTE_ACCESS_KEY`), not in the plugin's settings; the ID Token of an organization sign-in goes only to the relay the distribution preset, which the settings page cannot change.
 - The relay serves the page you open on your phone, so whoever runs the relay can change it. Use only relays you trust.
-- The DSH interface on your phone is provided by the computer it connects to and runs on the relay's domain, and browsers separate data only by domain. So the interface one computer provides can use this browser's pairings with other computers to connect to them. Pair only with your own computers.
-- Likewise, when the relay shares a domain with other sites, their scripts can use the pairings here to connect to computers, and the interface of any paired computer can use those sites as the user and read the data they keep in the browser. Give the relay a domain of its own (a subdomain, for example), and never share one with a sign-in service or other sites that you sign in to.
+- The DSH interface on your phone comes from the paired computer and shares the relay's origin. Browsers isolate data by origin (scheme, host and port), not path, so one computer's interface can use this browser's pairings with other computers to connect to them. Pair only with your own computers.
+- Likewise, sites sharing the relay's origin can use its pairings, and the interface of any paired computer can access those sites as the user and read browser data available to scripts. A separate domain narrows this trust boundary. Same-origin path integration accepts the shared boundary; neither path prefixes nor ordinary iframes provide isolation.
 - Pages allowed to embed the relay's page can show it within their own and cover parts of it to trick users into clicking (approving a command, say). Allow only pages you trust.
 
 See the [protocol document](docs/PROTOCOL.md) (Chinese) for details.

package/docs/DEPLOYMENT.md

@@ -0,0 +1,168 @@
+# 自托管中继部署
+
+[English](DEPLOYMENT_EN.md) · [插件使用与配对](../README.md)
+
+中继和桌面插件由同一个 npm 包 `@eduwork/dsh-remote-access` 交付。服务器只需运行包里的 `eduwork-remote-relay`，无需安装 EduWork 桌面客户端、模型服务或数据库。被访问的电脑运行 DSH/EduWork 和远控插件，其他终端通过浏览器访问中继的 HTTPS 地址。
+
+## 1. 启动服务
+
+准备 Node.js **24.22.1 或更新的受支持版本**、npm，以及可以转发 WebSocket 的 HTTPS 反向代理。以下命令固定使用 `0.1.1`，升级时明确修改版本号。
+
+先生成接入 Key，保存好并交给需要注册电脑的用户：
+
+```sh
+node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"
+```
+
+Linux/macOS 前台试运行：
+
+```sh
+export RELAY_URL='https://remote.example.edu/'
+export RELAY_ACCESS_KEYS='替换成刚才生成的Key'
+npx --yes --package=@eduwork/dsh-remote-access@0.1.1 eduwork-remote-relay
+```
+
+Windows PowerShell：
+
+```powershell
+$env:RELAY_URL = 'https://remote.example.edu/'
+$env:RELAY_ACCESS_KEYS = '替换成刚才生成的Key'
+npx --yes --package=@eduwork/dsh-remote-access@0.1.1 eduwork-remote-relay
+```
+
+默认监听 `127.0.0.1:8787`。`RELAY_URL` 是**用户访问的外部地址**，不是监听地址；TLS 在反向代理终止。前台命令退出就会停止服务，长期运行见第 3 节。只在本机调试时可使用 `http://localhost:8787/`；手机访问应使用具有有效证书的 HTTPS 地址，以便浏览器使用 Service Worker 和加密 API。
+
+## 2. HTTPS 与路径前缀
+
+独立域名可用 `RELAY_URL=https://remote.example.edu/`。同域路径可用：
+
+```dotenv
+RELAY_URL=https://example.edu/eduwork-remote/
+RELAY_ACCESS_KEYS=替换成随机Key
+RELAY_CLIENT_IP_HEADER=x-real-ip
+HOST=127.0.0.1
+PORT=8787
+```
+
+路径前缀由 `RELAY_URL` 决定，**没有另一个 PREFIX 环境变量**。客户端填写同一个完整地址。反向代理必须保留 `/eduwork-remote/`，网页、Service Worker、健康检查和 WebSocket 共用此前缀。
+
+Nginx 示例：把 `map` 放在 `http` 块中；把 `location` 放进已有证书配置的 HTTPS `server` 块中。根路径部署时把两个 `location` 替换为一个 `location /`，其余代理设置相同。
+
+```nginx
+# http 块内
+map $http_upgrade $eduwork_connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+# 已有 HTTPS server 块内
+location = /eduwork-remote {
+    return 301 /eduwork-remote/;
+}
+location /eduwork-remote/ {
+    # 不在 8787 后加 /，否则 Nginx 会去掉路径前缀。
+    proxy_pass http://127.0.0.1:8787;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection $eduwork_connection_upgrade;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+    proxy_buffering off;
+}
+```
+
+设置 `RELAY_CLIENT_IP_HEADER` 时，由可信代理覆盖该请求头，并让中继端口仅对该代理可达。同域已有 Service Worker 若控制整个站点，需要让它放过这段路径。
+
+路径划分不会隔离浏览器的同源存储和权限。远端 DSH 界面来自所配对的电脑，与中继页面同源；同域业务和被配对电脑必须处于部署者接受的共同信任范围。独立域名可以缩小这个范围。同域集成前请阅读 [安全说明](../README.md#安全)。
+
+## 3. 长期运行（Linux / systemd）
+
+由维护者安装固定版本；服务本身使用普通系统账号运行：
+
+```sh
+sudo useradd --system --no-create-home --shell /usr/sbin/nologin eduwork-remote
+sudo install -d /opt/eduwork-remote /etc/eduwork-remote
+sudo npm install --prefix /opt/eduwork-remote --omit=dev --ignore-scripts --save-exact @eduwork/dsh-remote-access@0.1.1
+sudo install -m 600 /dev/null /etc/eduwork-remote/relay.env
+```
+
+账号已存在时跳过 `useradd`。将第 2 节的配置写入 `/etc/eduwork-remote/relay.env`，填写实际 URL 和随机 Key。环境文件不要提交到仓库。将以下内容保存为 `/etc/systemd/system/eduwork-remote.service`：
+
+```ini
+[Unit]
+Description=EduWork remote relay
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=eduwork-remote
+Group=eduwork-remote
+WorkingDirectory=/opt/eduwork-remote
+EnvironmentFile=/etc/eduwork-remote/relay.env
+ExecStart=/usr/bin/node /opt/eduwork-remote/node_modules/@eduwork/dsh-remote-access/lib/relay.js
+Restart=on-failure
+RestartSec=3
+
+[Install]
+WantedBy=multi-user.target
+```
+
+先用 `command -v node` 核对 `ExecStart` 中的路径，确认该 Node 版本满足要求；不要依赖交互式 shell 才会加载的版本管理器。
+
+```sh
+sudo systemctl daemon-reload
+sudo systemctl enable --now eduwork-remote
+sudo systemctl status eduwork-remote
+sudo journalctl -u eduwork-remote -n 100 --no-pager
+```
+
+更改环境文件后执行 `sudo systemctl restart eduwork-remote`。更新 npm 包时在相同目录安装指定新版本后重启；保留 `package.json`、`package-lock.json` 和环境文件以便回退。中继重启会断开现有连接，在线电脑和设备会尝试重连。配对身份分别保存在电脑和远端浏览器中，中继不保存会话或配对数据库。
+
+## 4. 验证与配对
+
+路径部署示例：
+
+```sh
+curl -fsS http://127.0.0.1:8787/eduwork-remote/healthz
+curl -fsS https://example.edu/eduwork-remote/healthz
+curl -I https://example.edu/eduwork-remote/sw.js
+```
+
+前两项应返回 `ok`，第三项应返回 200 和 JavaScript 内容类型。健康检查只说明 HTTP 服务可达；还须在桌面“设置 → 远程访问”填写同一外部地址和 Key，启用后确认“已连接”。随后按[配对步骤](../README.md#添加和移除设备)从另一终端接入，并在本机核对配对码、确认授权。接入 Key 允许电脑使用中继，不能替代这次设备配对。
+
+## 5. 机构登录与 iframe（可选）
+
+机构登录可替代 Key，也可与 Key 并存：
+
+```dotenv
+RELAY_OIDC_ISSUER=https://sso.example.edu
+RELAY_OIDC_CLIENT_IDS=desktop-client-id
+RELAY_FRAME_ANCESTORS=self https://portal.example.edu
+```
+
+单用机构登录时不设 `RELAY_ACCESS_KEYS`。`issuer` 必须与 Token 的 `iss` 完全一致，client ID 是桌面应用的 OIDC 客户端标识；多个 ID 用逗号分隔。中继从 discovery/JWKS 获取公钥，当前支持 **RS256 ID Token**，校验签名、issuer、audience/authorized party 和有效期；这里不是模型 API Key，也不是拿 access token 充当 ID Token。
+
+电脑需安装 `@eduwork/dsh-oidc@0.3.1` 或后续兼容版本，并由发行版配置远控插件的 `organization: { relay, oidcProfileId }`。单纯设置服务端的 issuer 不会自动配置桌面登录。中继验证已有身份，不保存 refresh token，也不替用户登录；续期由电脑的 OIDC 插件处理。
+
+`RELAY_FRAME_ANCESTORS` 默认 `none`，禁止 iframe 嵌入。允许同源父页面时填 `self`，其他父页面填完整来源（协议、主机和可选端口，不含路径）。在 shell 中给多个来源加引号：`RELAY_FRAME_ANCESTORS="self https://portal.example.edu"`。父站自己的 CSP 也要允许加载中继，代理不能再给此路径附加冲突的 `X-Frame-Options: DENY` 或 `frame-ancestors 'none'`。
+
+```html
+<iframe src="https://example.edu/eduwork-remote/" title="远程访问"></iframe>
+```
+
+当前方案需要脚本、Service Worker 和同源身份，不能套一个移除同源身份的 sandbox；上述普通 iframe 示例不会提供安全隔离。跨站 iframe 在 Safari/WebKit 中可能无法加载电脑界面，优先使用同站集成或顶层打开中继。开放嵌入不改变本机配对与设备撤销要求。
+
+## 常见问题
+
+| 现象 | 优先检查 |
+| --- | --- |
+| 启动即退出，提示配置不完整 | `RELAY_URL`、Key 或完整 OIDC 配置是否实际进入进程环境。 |
+| healthz 正常，电脑仍无法连接 | HTTPS 证书、WebSocket Upgrade、外部 URL/前缀一致性、接入 Key；OIDC 模式还要检查 issuer/JWKS 可达性和 ID Token。 |
+| 子路径页面或 sw.js 返回 404 | `proxy_pass` 是否去掉了前缀，站点是否把此路径误转到另一个 SPA。 |
+| 手机卡在加载页面 | 有效 HTTPS、Service Worker 未被父站拦截、电脑在线且未休眠、浏览器站点数据未被清理。 |
+| 顶层能打开，iframe 打不开 | 中继 `RELAY_FRAME_ANCESTORS`、父页面 CSP、代理额外响应头，以及 WebKit 跨站限制。 |
+
+使用接入 Key 时不需要机构登录插件。API、帧格式和加密机制见[协议文档](PROTOCOL.md)。

package/docs/DEPLOYMENT_EN.md

@@ -0,0 +1,168 @@
+# Self-hosted relay deployment
+
+[简体中文](DEPLOYMENT.md) · [Plugin usage and pairing](../README_EN.md)
+
+The desktop plugin and relay ship in the same npm package, `@eduwork/dsh-remote-access`. The server runs `eduwork-remote-relay`; it does not need the EduWork desktop app, model services or a database. The accessed computer runs DSH/EduWork and the plugin, while other devices open the relay's HTTPS URL in a browser.
+
+## 1. Start the service
+
+Use Node.js **24.22.1 or a later supported version**, npm, and an HTTPS reverse proxy supporting WebSockets. These examples pin `0.1.1`; change the version explicitly when upgrading.
+
+Generate an access key, retain it and give it to the users registering computers:
+
+```sh
+node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"
+```
+
+Linux/macOS foreground run:
+
+```sh
+export RELAY_URL='https://remote.example.edu/'
+export RELAY_ACCESS_KEYS='replace-with-the-generated-key'
+npx --yes --package=@eduwork/dsh-remote-access@0.1.1 eduwork-remote-relay
+```
+
+Windows PowerShell:
+
+```powershell
+$env:RELAY_URL = 'https://remote.example.edu/'
+$env:RELAY_ACCESS_KEYS = 'replace-with-the-generated-key'
+npx --yes --package=@eduwork/dsh-remote-access@0.1.1 eduwork-remote-relay
+```
+
+The default listener is `127.0.0.1:8787`. `RELAY_URL` is the **external address users visit**, not the listening address. The proxy terminates TLS. Exiting the foreground command stops the service; see section 3 for persistent operation. Local-only debugging can use `http://localhost:8787/`; phones should use HTTPS with a valid certificate for Service Worker and cryptographic APIs.
+
+## 2. HTTPS and a path prefix
+
+A dedicated domain uses `RELAY_URL=https://remote.example.edu/`. To share a domain under a path:
+
+```dotenv
+RELAY_URL=https://example.edu/eduwork-remote/
+RELAY_ACCESS_KEYS=replace-with-a-random-key
+RELAY_CLIENT_IP_HEADER=x-real-ip
+HOST=127.0.0.1
+PORT=8787
+```
+
+`RELAY_URL` determines the prefix; **there is no separate PREFIX environment variable**. Enter the same complete URL on the computer. Preserve `/eduwork-remote/` in proxy requests: pages, Service Worker, health checks and WebSockets share that prefix.
+
+For Nginx, put `map` in the `http` block and the locations in an existing HTTPS `server` block with certificates configured. For a root-path deployment, replace the two locations with one `location /`, keeping the same proxy settings.
+
+```nginx
+# Inside http
+map $http_upgrade $eduwork_connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+# Inside the existing HTTPS server
+location = /eduwork-remote {
+    return 301 /eduwork-remote/;
+}
+location /eduwork-remote/ {
+    # No trailing / after 8787: preserve the path prefix.
+    proxy_pass http://127.0.0.1:8787;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection $eduwork_connection_upgrade;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+    proxy_buffering off;
+}
+```
+
+When using `RELAY_CLIENT_IP_HEADER`, let the trusted proxy overwrite that header and keep the relay port reachable only by that proxy. An existing site-wide Service Worker must leave this path alone.
+
+Paths do not isolate same-origin browser storage or privileges. The remote DSH interface comes from the paired computer and shares the relay's origin. The site's applications and paired computers must therefore belong to a trust boundary the operator accepts. A dedicated domain narrows that boundary. Read [Security](../README_EN.md#security) before sharing an origin.
+
+## 3. Persistent service (Linux / systemd)
+
+Have a maintainer install the pinned package; run the service as an ordinary system account:
+
+```sh
+sudo useradd --system --no-create-home --shell /usr/sbin/nologin eduwork-remote
+sudo install -d /opt/eduwork-remote /etc/eduwork-remote
+sudo npm install --prefix /opt/eduwork-remote --omit=dev --ignore-scripts --save-exact @eduwork/dsh-remote-access@0.1.1
+sudo install -m 600 /dev/null /etc/eduwork-remote/relay.env
+```
+
+Skip `useradd` if the account exists. Write the section 2 configuration to `/etc/eduwork-remote/relay.env`, using your URL and generated key. Do not commit the environment file. Save the following as `/etc/systemd/system/eduwork-remote.service`:
+
+```ini
+[Unit]
+Description=EduWork remote relay
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=eduwork-remote
+Group=eduwork-remote
+WorkingDirectory=/opt/eduwork-remote
+EnvironmentFile=/etc/eduwork-remote/relay.env
+ExecStart=/usr/bin/node /opt/eduwork-remote/node_modules/@eduwork/dsh-remote-access/lib/relay.js
+Restart=on-failure
+RestartSec=3
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Check the Node path using `command -v node` and adjust `ExecStart` as needed. Verify that binary meets the version requirement; do not rely on a version manager loaded only by interactive shells.
+
+```sh
+sudo systemctl daemon-reload
+sudo systemctl enable --now eduwork-remote
+sudo systemctl status eduwork-remote
+sudo journalctl -u eduwork-remote -n 100 --no-pager
+```
+
+After environment changes, run `sudo systemctl restart eduwork-remote`. To upgrade, install a specific new npm version in the same directory and restart. Retain `package.json`, `package-lock.json` and the environment file for rollback. A relay restart disconnects current connections; online computers and devices attempt to reconnect. Pairing identities live on the computer and remote browser; the relay stores no session or pairing database.
+
+## 4. Verify and pair
+
+For a path deployment:
+
+```sh
+curl -fsS http://127.0.0.1:8787/eduwork-remote/healthz
+curl -fsS https://example.edu/eduwork-remote/healthz
+curl -I https://example.edu/eduwork-remote/sw.js
+```
+
+The first two return `ok`; the last returns 200 with a JavaScript content type. Health checks establish HTTP reachability only. Enter the same external URL and key under desktop Settings → Remote access, enable it, and check for “Connected”. Follow the [pairing steps](../README_EN.md#add-and-remove-devices) on another device, compare codes and approve on the computer. An access key admits a computer to the relay; it does not replace device pairing.
+
+## 5. Organization sign-in and iframe (optional)
+
+Organization sign-in can replace access keys or coexist with them:
+
+```dotenv
+RELAY_OIDC_ISSUER=https://sso.example.edu
+RELAY_OIDC_CLIENT_IDS=desktop-client-id
+RELAY_FRAME_ANCESTORS=self https://portal.example.edu
+```
+
+Omit `RELAY_ACCESS_KEYS` when using organization sign-in alone. The issuer must exactly match the token's `iss`. Client IDs identify desktop applications registered with the issuer; separate multiple IDs with commas. Discovery/JWKS supplies public keys. The relay currently accepts **RS256 ID Tokens** and checks signatures, issuer, audience/authorized party and validity. This is neither a model API key nor an access token used as an ID Token.
+
+The computer needs `@eduwork/dsh-oidc@0.3.1` or a later compatible version, and distribution configuration for `organization: { relay, oidcProfileId }`. Setting an issuer on the server does not configure desktop login. The relay verifies existing identity, stores no refresh token and does not sign users in; the computer's OIDC plugin handles renewal.
+
+`RELAY_FRAME_ANCESTORS` defaults to `none`, blocking iframe embedding. Use `self` for same-origin parents, or complete origins (scheme, host and optional port, without paths). Quote multiple sources in shell commands: `RELAY_FRAME_ANCESTORS="self https://portal.example.edu"`. The parent's CSP must also permit the relay, and the proxy must not add a conflicting `X-Frame-Options: DENY` or `frame-ancestors 'none'` to this path.
+
+```html
+<iframe src="https://example.edu/eduwork-remote/" title="Remote access"></iframe>
+```
+
+The current design needs scripts, Service Worker and same-origin identity; an opaque-origin sandbox is incompatible. The ordinary iframe above provides no security isolation. Cross-site iframes may fail to load the computer's interface in Safari/WebKit; use same-site integration or open the relay at the top level. Allowing embedding does not replace local pairing or device revocation.
+
+## Troubleshooting
+
+| Symptom | Check first |
+| --- | --- |
+| Immediate exit with incomplete-configuration error | Ensure the process receives `RELAY_URL` and either access keys or complete OIDC settings. |
+| healthz works but the computer cannot connect | HTTPS certificate, WebSocket Upgrade, matching external URL/prefix and key; for OIDC, issuer/JWKS reachability and ID Token. |
+| Path page or sw.js returns 404 | Check for prefix removal by `proxy_pass` or routing to another site's SPA. |
+| Phone stays on the loading page | Valid HTTPS, no parent Service Worker interference, computer online and awake, browser site data retained. |
+| Top-level page works but iframe does not | Relay frame ancestors, parent CSP, proxy response headers and WebKit cross-site restrictions. |
+
+Access-key deployments do not need an organization login plugin. See the [protocol](PROTOCOL.md) for APIs, frames and encryption.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eduwork/dsh-remote-access",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "End-to-end encrypted remote access to a DSH host through a self-hosted relay",
   "type": "module",
   "license": "MIT",